Gasless Web3 Todo App — Demo

A premium, glassmorphic Todo List application demonstrating the plug-and-play capabilities of erc4337-kit.

This repository is a live demonstration of how erc4337-kit collapses the complex ERC-4337 Account Abstraction stack (Privy + Pimlico + Permissionless + Viem) into simple, zero-config React hooks. Users can sign up with social accounts (Google/Email), automatically obtain a deterministic Smart Account wallet, and interact with on-chain contracts with 100% sponsored gasless transactions.

---

⚡ Features Showcased

1. Social Authentication & Embedded Signers: Powered by Privy. Users sign in seamlessly without needing any browser extensions (like MetaMask).
2. Account Abstraction (ERC-4337): Automatically instantiates a deterministic Simple Smart Account for the authenticated user.
3. 100% Gasless Transaction Sponsorship: Integrates with Pimlico's Paymaster policy to sponsor transactions. Users pay $0 in gas.
4. On-Chain State Anchoring: Users can sync tasks to a Solidity contract (TodoList.sol) on Polygon Amoy.
5. Cryptographic Verification: Read from the contract using a standard JSON-RPC provider (Alchemy) to compare local state against the immutable blockchain anchor.
6. Simulate Tampering: Try tweaking a task locally to see the integrity check transition to "Out of Sync" and alert the user of modification during verification.

---

🛠️ How it uses erc4337-kit

This demo highlights the core zero-config hooks provided by the package:

• <ChainProvider>: Wraps the root of the app in main.jsx to set up all context providers (Privy, Wagmi, React Query, and ERC-4337 config).
• useWallet(): Manages authentication, deterministic smart account address retrieval, native balance, and logout.
• useStoreOnChain(): Executes gas-sponsored smart contract calls (under-the-hood user operation creation, sponsorship request, EOA signing, bundler submission, and fast block receipt polling).
• useContractRead(): Fetches on-chain historical records for the active smart account.

---

🚀 Getting Started

1. Installation

Clone the repository and install dependencies:

npm install

2. Configure API Keys

Create a .env file in the root directory based on .env.example:

# Privy App ID from https://dashboard.privy.io
VITE_PRIVY_APP_ID=your_privy_app_id_here

# Pimlico API Key from https://dashboard.pimlico.io
VITE_PIMLICO_API_KEY=your_pimlico_api_key_here

# Polygon Amoy RPC URL from https://dashboard.alchemy.com
VITE_RPC_URL=https://polygon-amoy.g.alchemy.com/v2/your_alchemy_key_here

# Solidity todo list contract address (automatically populated after deployment)
VITE_CONTRACT_ADDRESS=

3. Deploy the Smart Contract

Deploy your own TodoList contract to the Polygon Amoy testnet. Provide a private key containing testnet MATIC for contract deployment gas fees:

# Deploys contracts/TodoList.sol and updates VITE_CONTRACT_ADDRESS in .env
PRIVATE_KEY=your_deployment_private_key node deploy.js

4. Run the App

Start the local Vite development server:

npm run dev

Open http://localhost:5173 in your browser.

---

📦 Core Package Links

• Main Package Repository: erc4337-kit GitHub
• NPM registry: erc4337-kit on npm