{"id":32370237,"url":"https://github.com/hadv/ethaura","last_synced_at":"2025-10-24T20:24:57.432Z","repository":{"id":319832590,"uuid":"1076587860","full_name":"hadv/ethaura","owner":"hadv","description":"P256 Account Abstraction with Passkeys \u0026 Web3Auth","archived":false,"fork":false,"pushed_at":"2025-10-20T11:34:31.000Z","size":531,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-20T12:37:34.346Z","etag":null,"topics":["wallet","web3"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hadv.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-15T04:32:22.000Z","updated_at":"2025-10-20T03:47:39.000Z","dependencies_parsed_at":null,"dependency_job_id":"240e4b66-f205-48b3-a238-a34cf8daad15","html_url":"https://github.com/hadv/ethaura","commit_stats":null,"previous_names":["hadv/ethaura"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/hadv/ethaura","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hadv%2Fethaura","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hadv%2Fethaura/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hadv%2Fethaura/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hadv%2Fethaura/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hadv","download_url":"https://codeload.github.com/hadv/ethaura/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hadv%2Fethaura/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280859883,"owners_count":26403637,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-24T02:00:06.418Z","response_time":73,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["wallet","web3"],"created_at":"2025-10-24T20:24:54.056Z","updated_at":"2025-10-24T20:24:57.424Z","avatar_url":"https://github.com/hadv.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🔐 EthAura - P256 Account Abstraction with Passkeys \u0026 Web3Auth\n\nEthAura là một implementation hoàn chỉnh của ERC-4337 Account Abstraction sử dụng chữ ký P-256/secp256r1 và WebAuthn/Passkeys, kết hợp với Web3Auth cho social login. Dự án tận dụng EIP-7951 precompile có sẵn trên Sepolia testnet sau Fusaka upgrade để verify chữ ký P-256 một cách hiệu quả.\n\n**🆕 Now with Helios Light Client support for trustless RPC access!**\n\n## ✨ Tính năng\n\n### Smart Contract Features\n- ✅ **P-256 Signature Support**: Sử dụng đường cong secp256r1 thay vì secp256k1 truyền thống\n- ✅ **WebAuthn/Passkeys**: Tích hợp với Secure Enclave, Touch ID, Face ID, Windows Hello\n- ✅ **ERC-4337 Compatible**: Tuân thủ chuẩn Account Abstraction v0.7\n- ✅ **Gas Efficient**: Sử dụng native precompile (~6,900 gas) thay vì Solidity verification\n- ✅ **Two-Factor Authentication (2FA)**: Optional dual signature mode (passkey + owner key)\n- ✅ **Factory Pattern**: Deploy deterministic accounts với CREATE2\n- ✅ **EIP-1271 Support**: Tương thích với dApp signatures\n- 🛡️ **Guardian-Based Social Recovery**: Decentralized account recovery with multi-sig guardians (owner auto-added as first guardian)\n- ⏰ **Timelock Protection**: 48-hour delay for administrative changes, 24-hour for recovery\n- 🔒 **No Owner Bypass**: Owner cannot execute transactions directly (passkey required)\n\n### Frontend Features\n- 🔐 **Web3Auth Integration**: Social login (Google, Facebook, Twitter, Email)\n- 🔑 **No Seed Phrases**: Automatic wallet creation with Web3Auth\n- 🔒 **Automatic 2FA**: Auto-enable 2FA after account deployment\n- 👤 **User Profile**: Display user info (name, email, profile picture)\n- 📱 **Biometric Auth**: Touch ID/Face ID for transaction signing\n- 🎨 **Modern UI**: React + Vite with clean interface\n\n### Infrastructure Features\n- 🌐 **Helios Light Client**: Trustless, verified RPC access\n- 🔒 **Cryptographic Verification**: All RPC data verified locally\n- ⚡ **Fast Sync**: Light client syncs in seconds\n- 💾 **Minimal Storage**: No need for full node storage\n\n## 🏗️ Kiến trúc\n\n### Smart Contracts\n\n```\nsrc/\n├── P256Account.sol           # Main account contract\n├── P256AccountFactory.sol    # Factory for deploying accounts\n└── libraries/\n    ├── P256.sol             # P-256 verification library\n    └── WebAuthnLib.sol      # WebAuthn signature handling\n```\n\n### Frontend\n\n```\nfrontend/\n├── src/\n│   ├── components/\n│   │   ├── Web3AuthLogin.jsx       # Web3Auth social login\n│   │   ├── PasskeyManager.jsx      # Passkey creation\n│   │   ├── AccountManager.jsx      # Account deployment\n│   │   └── TransactionSender.jsx   # Transaction signing (2FA)\n│   ├── contexts/\n│   │   └── Web3AuthContext.jsx     # Web3Auth state management\n│   └── utils/\n│       ├── webauthn.js             # WebAuthn utilities\n│       └── signatureUtils.js       # Signature combining (2FA)\n```\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Node.js \u003e= 18\n- Foundry (for smart contracts)\n- Browser with WebAuthn support\n\n### 1. Clone và cài đặt dependencies\n\n```bash\n# Clone repository\ngit clone \u003cyour-repo-url\u003e\ncd ethaura\n\n# Install Foundry dependencies\nforge install OpenZeppelin/openzeppelin-contracts\nforge install eth-infinitism/account-abstraction\nforge install foundry-rs/forge-std\n\n# Install frontend dependencies\ncd frontend\nnpm install\n```\n\n### 2. Setup Web3Auth\n\n1. Go to [Web3Auth Dashboard](https://dashboard.web3auth.io/)\n2. Create a new project\n3. Select \"Plug and Play\" → \"Web\"\n4. Configure:\n   - **Project Name**: EthAura\n   - **Network**: Sapphire Devnet (testing) or Mainnet (production)\n   - **Whitelist URLs**: `http://localhost:5173` (and your production domain)\n5. Copy the **Client ID**\n\n### 3. Cấu hình environment\n\n**Backend (.env):**\n```bash\n# Copy .env.example to .env\ncp .env.example .env\n\n# Edit .env with your values\n# - SEPOLIA_RPC_URL: Your Sepolia RPC endpoint\n# - PRIVATE_KEY: Your deployer private key\n# - ETHERSCAN_API_KEY: For contract verification\n```\n\n**Frontend (frontend/.env):**\n```bash\n# Copy frontend/.env.example to frontend/.env\ncp frontend/.env.example frontend/.env\n\n# Edit frontend/.env with your values\nVITE_WEB3AUTH_CLIENT_ID=your_web3auth_client_id_here\nVITE_CHAIN_ID=11155111\nVITE_RPC_URL=https://rpc.sepolia.org\nVITE_FACTORY_ADDRESS=your_factory_address_after_deployment\nVITE_ENTRYPOINT_ADDRESS=0x0000000071727De22E5E9d8BAf0edAc6f37da032\n```\n\n### 4. Build và test contracts\n\n```bash\n# Build contracts\nforge build\n\n# Run tests (29 tests should pass)\nforge test\n\n# Run tests with gas report\nforge test --gas-report\n\n# Run tests on Sepolia fork\nforge test --fork-url $SEPOLIA_RPC_URL\n```\n\n### 5. Deploy contracts\n\n```bash\n# Deploy factory to Sepolia\nforge script script/Deploy.s.sol:DeployScript --rpc-url sepolia --broadcast --verify\n\n# Note the factory address from output\n# Update VITE_FACTORY_ADDRESS in frontend/.env\n```\n\n### 6. Run frontend\n\n```bash\ncd frontend\nnpm run dev\n```\n\nFrontend sẽ chạy tại `http://localhost:3000`\n\n## 📖 Cách sử dụng\n\n### 1. Login với Web3Auth\n\n1. Mở frontend demo tại `http://localhost:5173`\n2. Click \"🚀 Login with Web3Auth\"\n3. Chọn login method:\n   - 🔵 Google\n   - 🔵 Facebook\n   - 🐦 Twitter\n   - 📧 Email (Passwordless)\n4. Xác thực với social account\n5. Web3Auth wallet được tạo tự động (no seed phrases!)\n6. User info và wallet address được hiển thị\n\n### 2. Tạo Passkey\n\n1. Click \"Create Passkey\"\n2. Xác thực với Touch ID/Face ID/Windows Hello\n3. Passkey được lưu trong device\n4. Public key (qx, qy) sẽ được hiển thị\n\n### 3. Deploy Account với 2FA\n\n1. Nhập factory address (từ deployment)\n2. Owner address tự động lấy từ Web3Auth wallet\n3. Click \"🚀 Deploy Account with 2FA\"\n4. Account được deploy với 2FA enabled\n5. Account address sẽ được tạo deterministically\n\n### 4. Gửi Transaction với 2FA\n\n1. Nhập target address và amount\n2. Click \"🔐 Send Transaction (2FA)\"\n3. **Bước 1**: Ký với Passkey (Touch ID/Face ID)\n4. **Bước 2**: Ký với Web3Auth wallet (automatic)\n5. Signatures được combine (129 bytes)\n6. UserOperation được submit lên bundler\n7. EntryPoint validates cả 2 signatures\n8. Transaction executed! ✅\n\n### Signature Details\n\nKhi 2FA enabled, bạn sẽ thấy:\n- **Passkey Signature (P-256)**: r, s values (64 bytes)\n- **Owner Signature (ECDSA)**: Web3Auth wallet signature (65 bytes)\n- **Combined Signature**: 129 bytes total (ready for 2FA validation)\n\n## 🔧 Smart Contract API\n\n### P256Account\n\n```solidity\n// Initialize account\nfunction initialize(bytes32 qx, bytes32 qy, address owner) external\n\n// Validate UserOperation (ERC-4337)\nfunction validateUserOp(\n    PackedUserOperation calldata userOp,\n    bytes32 userOpHash,\n    uint256 missingAccountFunds\n) external returns (uint256 validationData)\n\n// Execute transaction\nfunction execute(address dest, uint256 value, bytes calldata func) external\n\n// Execute batch\nfunction executeBatch(\n    address[] calldata dest,\n    uint256[] calldata value,\n    bytes[] calldata func\n) external\n\n// EIP-1271 signature validation\nfunction isValidSignature(bytes32 hash, bytes calldata signature) \n    external view returns (bytes4)\n```\n\n### P256AccountFactory\n\n```solidity\n// Create new account\nfunction createAccount(\n    bytes32 qx,\n    bytes32 qy,\n    address owner,\n    uint256 salt\n) external returns (P256Account)\n\n// Get deterministic address\nfunction getAddress(\n    bytes32 qx,\n    bytes32 qy,\n    address owner,\n    uint256 salt\n) public view returns (address)\n\n// Get initCode for UserOperation\nfunction getInitCode(\n    bytes32 qx,\n    bytes32 qy,\n    address owner,\n    uint256 salt\n) external view returns (bytes memory)\n```\n\n## 🧪 Testing\n\n### Unit Tests\n\n```bash\n# Run all tests\nforge test\n\n# Run specific test file\nforge test --match-path test/P256.t.sol\n\n# Run with verbosity\nforge test -vvv\n\n# Run with gas report\nforge test --gas-report\n```\n\n### Test Coverage\n\n```bash\nforge coverage\n```\n\n## 🌐 Deployment\n\n### Sepolia Testnet\n\n```bash\n# Deploy factory\nforge script script/Deploy.s.sol:DeployScript \\\n  --rpc-url sepolia \\\n  --broadcast \\\n  --verify\n\n# Create account\nforge script script/CreateAccount.s.sol:CreateAccountScript \\\n  --rpc-url sepolia \\\n  --broadcast\n```\n\n### Mainnet (khi ready)\n\n```bash\n# CẢNH BÁO: Kiểm tra kỹ trước khi deploy mainnet!\nforge script script/Deploy.s.sol:DeployScript \\\n  --rpc-url mainnet \\\n  --broadcast \\\n  --verify\n```\n\n## 📚 Technical Details\n\n### EIP-7951 Precompile\n\n- **Address**: `0x0100`\n- **Input**: `hash(32) || r(32) || s(32) || qx(32) || qy(32)` (160 bytes)\n- **Output**: `0x01` (32 bytes) if valid, empty if invalid\n- **Gas Cost**: ~6,900 gas (draft)\n\n### Signature Format\n\n**Normal Mode (2FA disabled)**:\n```\nsignature = r || s (64 bytes)\nmessageHash = SHA256(userOpHash)\n```\n\n**2FA Mode (2FA enabled)**:\n```\nsignature = r || s || ownerSignature (129 bytes)\n  where:\n    r, s = P-256 signature (32 + 32 = 64 bytes)\n    ownerSignature = ECDSA signature (r + s + v = 65 bytes)\nmessageHash = SHA256(userOpHash)\n```\n\n**WebAuthn Mode** (optional):\n```\nsignature = r || s (64 bytes, decoded from DER)\nmessageHash = SHA256(authenticatorData || SHA256(clientDataJSON))\n```\n\n### Security Considerations\n\n1. **Malleability Protection**: Enforces `s \u003c= N/2` for both P-256 and ECDSA\n2. **Replay Protection**: Uses EntryPoint nonce\n3. **Access Control**: Owner-based permissions\n4. **Reentrancy**: Uses checks-effects-interactions pattern\n5. **Two-Factor Authentication**: Optional dual signature validation\n6. **Web3Auth Security**: MPC-based key management, non-custodial\n\n## 🛠️ Development\n\n### Project Structure\n\n```\nethaura/\n├── src/                    # Smart contracts\n├── test/                   # Contract tests\n├── script/                 # Deployment scripts\n├── frontend/               # React frontend\n├── foundry.toml           # Foundry config\n└── README.md              # This file\n```\n\n### Adding New Features\n\n1. Write contract in `src/`\n2. Add tests in `test/`\n3. Update frontend if needed\n4. Run tests: `forge test`\n5. Deploy and verify\n\n## 📚 Documentation\n\n### Core Documentation\n- [Two-Factor Authentication Guide](docs/TWO_FACTOR_AUTH.md) - Complete guide for 2FA feature\n- [Web3Auth Integration Guide](docs/WEB3AUTH_INTEGRATION.md) - Social login setup and usage\n- [2FA Implementation Summary](docs/2FA_IMPLEMENTATION_SUMMARY.md) - Technical implementation details\n- [Architecture Overview](ARCHITECTURE.md) - System architecture and design\n- [Security Considerations](SECURITY.md) - Security best practices\n- [Deployment Guide](DEPLOYMENT.md) - How to deploy to testnet/mainnet\n\n### Infrastructure Documentation\n- **[Production Setup Guide](PRODUCTION_SETUP.md)** - Complete production deployment guide\n- [Helios Quick Start](HELIOS_QUICKSTART.md) - 5-minute Helios setup\n- [Helios Setup Guide](docs/HELIOS_SETUP.md) - Comprehensive Helios configuration\n- [Consensus Node Setup](docs/CONSENSUS_NODE_SETUP.md) - Production consensus node (Linux)\n- [Helios Architecture](docs/HELIOS_ARCHITECTURE.md) - Architecture deep dive\n\n### Quick Links\n- **Smart Contracts**: See `src/` directory\n- **Tests**: See `test/` directory (29/29 passing)\n- **Frontend**: See `frontend/` directory\n- **Demo Script**: See `script/Demo2FA.s.sol`\n\n## 🔗 Resources\n\n### Ethereum Standards\n- [EIP-7951: P256 Precompile](https://eips.ethereum.org/EIPS/eip-7951)\n- [ERC-4337: Account Abstraction](https://eips.ethereum.org/EIPS/eip-4337)\n- [EIP-1271: Signature Validation](https://eips.ethereum.org/EIPS/eip-1271)\n\n### Web3Auth\n- [Web3Auth Documentation](https://web3auth.io/docs/)\n- [Web3Auth Dashboard](https://dashboard.web3auth.io/)\n- [Web3Auth Examples](https://github.com/Web3Auth/web3auth-pnp-examples)\n\n### WebAuthn/Passkeys\n- [WebAuthn Specification](https://www.w3.org/TR/webauthn-2/)\n- [WebAuthn Guide](https://webauthn.guide/)\n- [Passkeys.dev](https://passkeys.dev/)\n\n### Other\n- [Sepolia Fusaka Upgrade](https://cointelegraph.com/news/ethereum-fusaka-testnet-sepolia)\n- [Account Abstraction Docs](https://docs.alchemy.com/docs/account-abstraction-overview)\n\n## 📝 License\n\nMIT License - see LICENSE file for details\n\n## 🤝 Contributing\n\nContributions are welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch\n3. Add tests for new features\n4. Submit a pull request\n\n## ⚠️ Disclaimer\n\nThis is experimental software. Use at your own risk. Not audited for production use.\n\n## 📧 Contact\n\nFor questions or support, please open an issue on GitHub.\n\n---\n\nBuilt with ❤️ using Foundry, React, and WebAuthn\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhadv%2Fethaura","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhadv%2Fethaura","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhadv%2Fethaura/lists"}