{"_id":"@anuragchvn-blip/mandatekit","name":"@anuragchvn-blip/mandatekit","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@anuragchvn-blip/mandatekit","version":"1.0.0","description":"Production-ready Web3 autopay SDK for crypto-based recurring payments using EIP-712 mandates","type":"module","main":"./dist/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"},"./client":{"types":"./dist/client/index.d.ts","import":"./dist/client/index.js"},"./relayer":{"types":"./dist/relayer/index.d.ts","import":"./dist/relayer/index.js"},"./utils":{"types":"./dist/utils/index.d.ts","import":"./dist/utils/index.js"},"./adapters":{"types":"./dist/adapters/index.d.ts","import":"./dist/adapters/index.js"},"./contracts":{"types":"./dist/contracts/index.d.ts","import":"./dist/contracts/index.js"}},"sideEffects":false,"scripts":{"build":"tsc","dev":"tsc --watch","test":"vitest","test:coverage":"vitest --coverage","lint":"eslint src --ext .ts","format":"prettier --write \"src/**/*.ts\"","prepare":"npm run build"},"keywords":["web3","autopay","recurring-payments","eip-712","mandate","ethereum","crypto","subscription","pull-payment"],"author":{"name":"anuragchvn-blip"},"license":"MIT","peerDependencies":{"viem":"^2.0.0"},"devDependencies":{"@types/node":"^20.10.0","@typescript-eslint/eslint-plugin":"^6.15.0","@typescript-eslint/parser":"^6.15.0","eslint":"^8.56.0","prettier":"^3.1.1","typescript":"^5.3.3","viem":"^2.0.0","vitest":"^1.0.4"},"repository":{"type":"git","url":"git+https://github.com/anuragchvn-blip/MandateKit.git"},"_id":"@anuragchvn-blip/mandatekit@1.0.0","gitHead":"b193d20a2b1246a571f03396183b01dacd754501","bugs":{"url":"https://github.com/anuragchvn-blip/MandateKit/issues"},"homepage":"https://github.com/anuragchvn-blip/MandateKit#readme","_nodeVersion":"22.17.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-lqPDUmTKU9ihY2Jx3ewUswJvHGNJgdV2pd4Ul8vzmF32He4TsYcZG2YN9IIfIBLpknXqY4Z+X8yYNAVIdsapiQ==","shasum":"3ceb42e63ae16db8c526e5e43ee18c626f0a8377","tarball":"https://registry.npmjs.org/@anuragchvn-blip/mandatekit/-/mandatekit-1.0.0.tgz","fileCount":47,"unpackedSize":200381,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDIuyNlfxEXB5NtO97S2VcAMa7eWeAhy1dC2hUfrILiyAIhAIRVRWdDzWjnF2wWUv5Sekh2uJvZ17KEGzROBYw+y8jt"}]},"_npmUser":{"name":"anuragchvn-blip","email":"21bsr14009@jainuniversity.ac.in"},"directories":{},"maintainers":[{"name":"anuragchvn-blip","email":"21bsr14009@jainuniversity.ac.in"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mandatekit_1.0.0_1763196523195_0.4245344971465652"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-15T08:48:43.121Z","1.0.0":"2025-11-15T08:48:43.431Z","modified":"2025-11-15T08:48:43.708Z"},"maintainers":[{"name":"anuragchvn-blip","email":"21bsr14009@jainuniversity.ac.in"}],"description":"Production-ready Web3 autopay SDK for crypto-based recurring payments using EIP-712 mandates","homepage":"https://github.com/anuragchvn-blip/MandateKit#readme","keywords":["web3","autopay","recurring-payments","eip-712","mandate","ethereum","crypto","subscription","pull-payment"],"repository":{"type":"git","url":"git+https://github.com/anuragchvn-blip/MandateKit.git"},"author":{"name":"anuragchvn-blip"},"bugs":{"url":"https://github.com/anuragchvn-blip/MandateKit/issues"},"license":"MIT","readme":"# 🚀 MandateKit\r\n\r\n**Production-ready Web3 autopay SDK for crypto-based recurring payments on Polygon**\r\n\r\nMandateKit 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.\r\n\r\n[![npm version](https://badge.fury.io/js/%40anuragchvn-blip%2Fmandatekit.svg)](https://github.com/anuragchvn-blip/MandateKit/packages)\r\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\r\n\r\n## 🌟 Live Deployment\r\n\r\n**Smart Contract Address (Polygon Mainnet):**\r\n```\r\n0xd9145CCE52D386f254917e481eB44e9943F39138\r\n```\r\n\r\nView on [PolygonScan](https://polygonscan.com/address/0xd9145CCE52D386f254917e481eB44e9943F39138)\r\n\r\n## ✨ Features\r\n\r\n- 🔐 **EIP-712 Typed Signatures** - Secure, human-readable mandate signing (no phishing)\r\n- 🤖 **Relayer Automation** - Automated pull-based payment execution with fee incentives\r\n- ⏰ **Cadence Enforcement** - Flexible scheduling (daily, weekly, monthly, yearly, custom)\r\n- 🔄 **Replay Protection** - Built-in nonce and timestamp validation\r\n- 🛡️ **Security Hardened** - Checks-Effects-Interactions pattern, ReentrancyGuard\r\n- 💰 **Non-Custodial** - Users always maintain control of their funds\r\n- 🧩 **Modular & Tree-shakeable** - Import only what you need\r\n- 💪 **TypeScript First** - Full type safety and IntelliSense\r\n- 🔌 **Adapter Support** - Permit2, vaults, account abstraction ready\r\n- 📦 **Modern Stack** - Built with Viem v2, ES2020+, OpenZeppelin v5\r\n\r\n## 📦 Installation\r\n\r\n### From GitHub Packages\r\n\r\n```bash\r\n# Configure npm to use GitHub Packages\r\necho \"@anuragchvn-blip:registry=https://npm.pkg.github.com\" >> .npmrc\r\n\r\n# Install the package\r\nnpm install @anuragchvn-blip/mandatekit viem\r\n```\r\n\r\n### From npm (Coming Soon)\r\n\r\n```bash\r\nnpm install @anuragchvn-blip/mandatekit viem\r\n```\r\n\r\n## 🏃 Quick Start\r\n\r\n### Backend (Node.js)\r\n\r\n```typescript\r\nimport { createMandateClient } from '@anuragchvn-blip/mandatekit/client';\r\nimport { privateKeyToAccount } from 'viem/accounts';\r\nimport { polygon } from 'viem/chains';\r\n\r\nconst account = privateKeyToAccount('0x...');\r\nconst client = createMandateClient({ \r\n  account,\r\n  chain: polygon \r\n});\r\n\r\n// Create a mandate for recurring USDC payments\r\nconst mandate = await client.signMandate({\r\n  subscriber: '0x123...', // Payer address\r\n  token: '0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174', // USDC on Polygon\r\n  amount: '10000000', // 10 USDC (6 decimals)\r\n  cadence: { interval: 'monthly', count: 1 },\r\n  recipient: '0x456...', // Recipient address\r\n  validAfter: Math.floor(Date.now() / 1000),\r\n  validBefore: Math.floor(Date.now() / 1000) + 31536000, // 1 year\r\n  maxPayments: 12, // Optional: auto-cancel after 12 payments\r\n  metadata: 'Netflix subscription', // Optional\r\n});\r\n\r\nconsole.log('Mandate ID:', mandate.mandateId);\r\nconsole.log('Signature:', mandate.signature);\r\n```\r\n\r\n### Frontend (Browser with MetaMask)\r\n\r\n```typescript\r\nimport { createMandateClient } from '@anuragchvn-blip/mandatekit/client';\r\nimport { createWalletClient, custom } from 'viem';\r\nimport { polygon } from 'viem/chains';\r\n\r\nconst walletClient = createWalletClient({\r\n  chain: polygon,\r\n  transport: custom(window.ethereum),\r\n});\r\n\r\nconst [address] = await walletClient.getAddresses();\r\nconst client = createMandateClient({ \r\n  walletClient, \r\n  address \r\n});\r\n\r\n// User signs mandate in MetaMask\r\nconst mandate = await client.signMandate({\r\n  subscriber: address,\r\n  token: '0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174', // USDC\r\n  amount: '10000000', // 10 USDC\r\n  cadence: { interval: 'monthly', count: 1 },\r\n  recipient: '0x456...',\r\n  validAfter: Math.floor(Date.now() / 1000),\r\n  validBefore: Math.floor(Date.now() / 1000) + 31536000,\r\n});\r\n\r\n// Register mandate on-chain\r\nconst txHash = await client.registerMandate(mandate);\r\nconsole.log('Registered:', txHash);\r\n```\r\n\r\n### Relayer (Automated Execution)\r\n\r\n```typescript\r\nimport { createRelayerClient } from '@anuragchvn-blip/mandatekit/relayer';\r\nimport { privateKeyToAccount } from 'viem/accounts';\r\nimport { polygon } from 'viem/chains';\r\n\r\nconst relayerAccount = privateKeyToAccount('0x...');\r\nconst relayer = createRelayerClient({\r\n  account: relayerAccount,\r\n  chain: polygon,\r\n  registryAddress: '0xd9145CCE52D386f254917e481eB44e9943F39138',\r\n  pollInterval: 60000, // Check every minute\r\n});\r\n\r\n// Schedule mandate for automated execution\r\nawait relayer.scheduleMandate(mandate);\r\n\r\n// Relayer earns 0.5% fee for executing payments\r\nconsole.log('Relayer monitoring active mandates...');\r\n```\r\n\r\n## 📚 Documentation\r\n\r\n- **[API Reference](./docs/API.md)** - Complete API documentation\r\n- **[Examples](./examples/)** - Full working examples\r\n- **[Smart Contract](./contracts/)** - Solidity source code\r\n- **[Security](./SECURITY.md)** - Security practices and audit info\r\n\r\n## 🎯 Use Cases\r\n\r\n- 💳 **Subscription Services** - Netflix-style recurring billing in crypto\r\n- 💼 **Payroll** - Pay employees/contractors on a schedule\r\n- 📈 **Dollar-Cost Averaging (DCA)** - Automated periodic token purchases\r\n- 🏠 **Rent/Bills** - Recurring payments for utilities, rent, etc.\r\n- 🎮 **Gaming** - Season passes and recurring in-game purchases\r\n- 📱 **SaaS** - Decentralized software subscriptions\r\n\r\n## 🏗️ Architecture\r\n\r\n```text\r\nMandateKit\r\n├── client/       → Mandate signing & verification (EIP-712)\r\n├── relayer/      → Automated execution engine\r\n├── contracts/    → Smart contract ABIs & addresses\r\n├── utils/        → Cryptographic & validation utilities\r\n└── adapters/     → Protocol integrations (Permit2, vaults, AA)\r\n```\r\n\r\n## 🔒 Security\r\n\r\n### Smart Contract Security\r\n\r\n- ✅ **Checks-Effects-Interactions Pattern** - Prevents reentrancy attacks\r\n- ✅ **ReentrancyGuard** - OpenZeppelin's reentrancy protection\r\n- ✅ **SafeERC20** - Secure token transfers with proper error handling\r\n- ✅ **Nonce-based Replay Protection** - Each mandate uses unique nonce\r\n- ✅ **Timestamp Validation** - Enforces validAfter/validBefore windows\r\n- ✅ **Cadence Enforcement** - Contract-level payment scheduling\r\n- ✅ **Signature Verification** - EIP-712 typed data signatures\r\n- ✅ **Owner Access Control** - Only owner can modify critical parameters\r\n\r\n### SDK Security\r\n\r\n- ✅ **EIP-712 Typed Data** - Human-readable signatures prevent phishing\r\n- ✅ **Input Validation** - Comprehensive validation before signing\r\n- ✅ **TypeScript Type Safety** - Compile-time error prevention\r\n- ✅ **No Private Key Storage** - Uses viem's secure account handling\r\n\r\n### Deployed Contract\r\n\r\n**Polygon Mainnet:** `0xd9145CCE52D386f254917e481eB44e9943F39138`\r\n\r\n- Owner: `0x5B38Da6a701c568545dCfcB03FcB875f56beddC4`\r\n- Fee Collector: `0x2913411D27f5d6716590F952b50088779Ae4a699`\r\n- Relayer Fee: 0.5% (50 basis points)\r\n- Max Fee Cap: 5% (500 basis points)\r\n\r\n## 🛠️ Development\r\n\r\n### Setup\r\n\r\n```bash\r\n# Clone repository\r\ngit clone https://github.com/anuragchvn-blip/MandateKit.git\r\ncd MandateKit\r\n\r\n# Install dependencies\r\nnpm install\r\n\r\n# Build SDK\r\nnpm run build\r\n\r\n# Run examples\r\nnpm run example:backend\r\nnpm run example:relayer\r\n```\r\n\r\n### Publishing to GitHub Packages\r\n\r\n```bash\r\n# Authenticate with GitHub\r\nnpm login --registry=https://npm.pkg.github.com\r\n\r\n# Build and publish\r\nnpm run build\r\nnpm publish\r\n```\r\n\r\n## 🤝 Contributing\r\n\r\nContributions are welcome! Please read our [Contributing Guide](./CONTRIBUTING.md) first.\r\n\r\n## 📄 License\r\n\r\nMIT © 2025 MandateKit\r\n\r\n## 🔗 Links\r\n\r\n- **Repository:** [github.com/anuragchvn-blip/MandateKit](https://github.com/anuragchvn-blip/MandateKit)\r\n- **Issues:** [github.com/anuragchvn-blip/MandateKit/issues](https://github.com/anuragchvn-blip/MandateKit/issues)\r\n- **Polygon Contract:** [0xd9145CCE52D386f254917e481eB44e9943F39138](https://polygonscan.com/address/0xd9145CCE52D386f254917e481eB44e9943F39138)\r\n\r\n## ⚠️ Disclaimer\r\n\r\nThis 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.\r\n","readmeFilename":"README.md","_rev":"1-1b42d7094abcbdfc88f5a80d1893a743"}