d-bis/metamask-integration
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: sync submodule state (parent ref update)

Browse Source 
Made-with: Cursor
This commit is contained in:
defiQUG
2026-03-02 12:14:14 -08:00
parent b6a776e5d7
commit 25c96e210a
316 changed files with 29779 additions and 677 deletions
Download Patch File Download Diff File Expand all files Collapse all files

281
docs/BRIDGE_INTEGRATION_GUIDE.md Normal file
View File

@@ -0,0 +1,281 @@
# Bridge Integration Guide for ChainID 138
Complete guide for integrating bridge functionality with MetaMask on ChainID 138.
## Overview
This guide covers bridge integration options for ChainID 138, enabling users to transfer assets between ChainID 138 and other networks.
## Bridge Options
### Option 1: Partner with Existing Bridge Providers
#### Recommended Providers
1. **LayerZero**
- Cross-chain messaging protocol
- Supports multiple chains
- Well-established infrastructure
- **Contact**: https://layerzero.network
2. **Wormhole**
- Cross-chain bridge protocol
- Supports 30+ chains
- Security audited
- **Contact**: https://wormhole.com
3. **Axelar**
- Cross-chain communication
- Supports multiple chains
- Developer-friendly
- **Contact**: https://axelar.network
4. **Stargate**
- LayerZero-based bridge
- Optimized for stablecoins
- High liquidity
- **Contact**: https://stargate.finance
#### Integration Steps
1. **Contact Bridge Provider**:
- Request ChainID 138 integration
- Provide network information
- Discuss integration requirements
2. **Technical Requirements**:
- RPC endpoints (provided)
- Token contracts (deployed)
- Network stability (verified)
- Security audit (if required)
3. **Integration Process**:
- Deploy bridge contracts on ChainID 138
- Configure bridge endpoints
- Test bridge functionality
- Launch bridge
### Option 2: Implement Custom Bridge
#### Architecture
```
┌─────────────┐ ┌──────────────┐ ┌─────────────┐
│ ChainID 1 │ ──────► │ Bridge Router│ ◄────── │ ChainID │
│ (Ethereum) │ │ │ │ 138 │
└─────────────┘ └──────────────┘ └─────────────┘
│
▼
┌──────────────┐
│ Validators │
│ / Relayers │
└──────────────┘
```
#### Components
1. **Lockbox Contract** (ChainID 138)
- Locks tokens on source chain
- Emits lock events
- Handles unlocks
2. **Inbox Contract** (Destination Chain)
- Receives bridge messages
- Mints/burns tokens
- Validates messages
3. **Bridge Router**
- Routes messages between chains
- Validates transactions
- Manages liquidity
4. **Relayer Network**
- Monitors lock events
- Submits unlock transactions
- Provides redundancy
#### Implementation Steps
1. **Deploy Contracts**:
```bash
# Deploy Lockbox on ChainID 138
forge script script/bridge/DeployLockbox.s.sol --rpc-url $RPC_URL_138
# Deploy Inbox on destination chain
forge script script/bridge/DeployInbox.s.sol --rpc-url $DEST_RPC
```
2. **Configure Bridge**:
- Set up relayer network
- Configure message routing
- Set up monitoring
3. **Security Audit**:
- Conduct security audit
- Fix identified issues
- Deploy audited contracts
4. **Testing**:
- Test bridge functionality
- Test edge cases
- Test security scenarios
### Option 3: Use Bridge Aggregator
#### Aggregators
1. **Socket.tech**
- Bridge aggregator
- Supports multiple bridges
- Best route selection
- **Integration**: https://docs.socket.tech
2. **LI.FI**
- Cross-chain bridge aggregator
- Supports 30+ chains
- SDK available
- **Integration**: https://docs.li.fi
3. **Bungee Exchange**
- Bridge aggregator
- Supports multiple chains
- Simple integration
- **Integration**: https://docs.bungee.exchange
## MetaMask Bridge Integration
### Requirements
1. **Bridge Provider Partnership**:
- Partner with bridge provider
- Get bridge API access
- Configure bridge endpoints
2. **Token Support**:
- Supported tokens on both chains
- Liquidity on both sides
- Token metadata complete
3. **Security**:
- Security audit completed
- Monitoring in place
- Risk management
4. **Consensys Approval**:
- Submit bridge for MetaMask approval
- Provide security documentation
- Complete integration review
### Integration Process
1. **Phase 1: Bridge Setup** (Month 1-2)
- Deploy bridge contracts
- Configure bridge endpoints
- Test bridge functionality
2. **Phase 2: Security Audit** (Month 2-3)
- Conduct security audit
- Fix identified issues
- Deploy audited contracts
3. **Phase 3: MetaMask Integration** (Month 3-6)
- Submit to MetaMask
- Complete integration review
- Test MetaMask integration
- Launch bridge
## Bridge Configuration
### Supported Tokens
- **cUSDT**: Bridgeable to/from Ethereum Mainnet
- **cUSDC**: Bridgeable to/from Ethereum Mainnet
- **WETH**: Bridgeable to/from Ethereum Mainnet
- **LINK**: Bridgeable to/from Ethereum Mainnet
### Bridge Fees
- **Bridge Fee**: 0.1% - 0.5% (configurable)
- **Gas Fees**: Paid by user
- **Relayer Fees**: Included in bridge fee
### Bridge Limits
- **Minimum**: 1 token (or equivalent)
- **Maximum**: Based on liquidity
- **Daily Limit**: Configurable per token
## Testing
### Test Scenarios
1. **Basic Bridge**:
- Bridge tokens from ChainID 138 to Ethereum
- Bridge tokens from Ethereum to ChainID 138
- Verify balances on both chains
2. **Edge Cases**:
- Bridge minimum amount
- Bridge maximum amount
- Bridge during high congestion
- Bridge with failed transactions
3. **Security**:
- Test invalid messages
- Test replay attacks
- Test double-spend prevention
- Test validator rotation
## Monitoring
### Metrics to Monitor
- Bridge transaction volume
- Bridge success rate
- Bridge fees collected
- Bridge latency
- Liquidity levels
- Security events
### Alerts
- Failed bridge transactions
- Low liquidity warnings
- Security incidents
- High latency alerts
## Documentation
### User Documentation
- How to bridge tokens
- Bridge fees and limits
- Bridge time estimates
- Troubleshooting guide
### Developer Documentation
- Bridge API documentation
- Integration examples
- SDK documentation
- Contract addresses
## Support
### User Support
- Bridge transaction issues
- Bridge fee questions
- Bridge time questions
- Troubleshooting
### Developer Support
- Integration help
- API questions
- Contract questions
- Testing support
---
**Last Updated**: 2026-01-26

88
docs/COMMUNITY_SUPPORT_GUIDE.md Normal file
View File

@@ -0,0 +1,88 @@
# Community Support Setup Guide
**Date**: 2026-01-26
**Network**: ChainID 138 (SMOM-DBIS-138)
---
## Overview
This guide explains how to set up community support channels for Smart Accounts.
---
## Support Channels
### 1. Documentation
**Primary Resources**:
- User Guide: `docs/SMART_ACCOUNTS_USER_GUIDE.md`
- Developer Guide: `docs/SMART_ACCOUNTS_DEVELOPER_GUIDE.md`
- FAQ: `docs/SMART_ACCOUNTS_FAQ.md`
- Troubleshooting: `docs/SMART_ACCOUNTS_TROUBLESHOOTING.md`
### 2. Community Forums
**Options**:
- Discord server
- GitHub Discussions
- Forum platform
- Reddit community
### 3. Support Tickets
**System**: GitHub Issues
**Labels**:
- `smart-accounts`
- `bug`
- `feature-request`
- `question`
- `documentation`
---
## FAQ Preparation
### Common Questions
1. **What are Smart Accounts?**
- See FAQ document
2. **How do I create a Smart Account?**
- See User Guide
3. **How do I use delegation?**
- See Delegation Guide
4. **Troubleshooting issues?**
- See Troubleshooting Guide
---
## Support Workflow
### 1. User Question
- Check FAQ first
- Check documentation
- Search existing issues
### 2. Escalation
- Simple question → FAQ/documentation
- Bug report → GitHub issue
- Feature request → GitHub issue
- Complex issue → Support team
---
## Resources
- [FAQ Document](./SMART_ACCOUNTS_FAQ.md)
- [Troubleshooting Guide](./SMART_ACCOUNTS_TROUBLESHOOTING.md)
- [User Guide](./SMART_ACCOUNTS_USER_GUIDE.md)
---
**Last Updated**: 2026-01-26

428
docs/COMMUNITY_SUPPORT_SETUP.md Normal file
View File

@@ -0,0 +1,428 @@
# Community Support Setup Guide
Complete guide for setting up community support channels for MetaMask integration with ChainID 138.
## Overview
This guide covers setting up support channels, documentation, and processes to help users with MetaMask integration on ChainID 138.
---
## Support Channels
### 1. Discord Server
**Setup**:
1. Create Discord server
2. Set up channels:
- `#general` - General discussion
- `#support` - User support
- `#developers` - Developer support
- `#announcements` - Updates and announcements
- `#feedback` - Feature requests and feedback
**Configuration**:
- Bot for automated responses
- Role-based permissions
- Moderation tools
- FAQ bot
**Invite Link**: [To be created]
---
### 2. GitHub Discussions
**Setup**:
1. Enable GitHub Discussions in repository
2. Create categories:
- Q&A
- General Discussion
- Ideas
- Show and Tell
**Benefits**:
- Integrated with codebase
- Searchable
- Version controlled
- Developer-friendly
**Repository**: [GitHub repo URL]
---
### 3. Telegram Group
**Setup**:
1. Create Telegram group
2. Set up bot for moderation
3. Create pinned messages with FAQs
4. Set up rules and guidelines
**Configuration**:
- Admin roles
- Moderation bot
- Welcome message
- FAQ bot
**Invite Link**: [To be created]
---
### 4. Support Email
**Setup**:
1. Create support email: `support@d-bis.org`
2. Set up email ticketing system
3. Configure auto-responders
4. Set up email templates
**Templates**:
- Welcome email
- Acknowledgment email
- Resolution email
- Follow-up email
---
### 5. Documentation Site
**Setup**:
1. Create documentation site
2. Organize by topic:
- Getting Started
- User Guides
- Developer Guides
- Troubleshooting
- FAQ
**Platform Options**:
- GitHub Pages
- GitBook
- Docusaurus
- Read the Docs
---
## FAQ Document
### Common Questions
#### Q: How do I add ChainID 138 to MetaMask?
**A**:
1. Open MetaMask
2. Click network dropdown
3. Click "Add Network"
4. Enter network details:
- Network Name: DeFi Oracle Meta Mainnet
- RPC URL: https://rpc.d-bis.org
- Chain ID: 138
- Currency Symbol: ETH
- Block Explorer: https://explorer.d-bis.org
5. Click "Save"
Or use the programmatic method:
```javascript
await window.ethereum.request({
method: 'wallet_addEthereumChain',
params: [{
chainId: '0x8a',
chainName: 'DeFi Oracle Meta Mainnet',
rpcUrls: ['https://rpc.d-bis.org'],
nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
blockExplorerUrls: ['https://explorer.d-bis.org']
}]
});
```
---
#### Q: How do I add cUSDT or cUSDC tokens?
**A**:
1. Connect to ChainID 138
2. Click "Import tokens"
3. Enter token address:
- cUSDT: `0x93E66202A11B1772E55407B32B44e5Cd8eda7f22`
- cUSDC: `0xf22258f57794CC8E06237084b353Ab30fFfa640b`
4. Verify decimals are set to **6** (important!)
5. Click "Add Custom Token"
---
#### Q: Why are decimals not showing correctly?
**A**: MetaMask may have cached incorrect metadata. Fix:
1. Remove the token from MetaMask
2. Re-add the token
3. **Manually set decimals to 6** for cUSDT/cUSDC
4. Or import the updated token list
See: [Fix cUSDT/cUSDC Decimals Guide](./FIX_CUSDT_CUSDC_DECIMALS.md)
---
#### Q: Can I use MetaMask Swaps on ChainID 138?
**A**: Not yet. MetaMask Swaps doesn't currently support ChainID 138. Use DEX UIs that support ChainID 138 instead.
---
#### Q: Can I bridge to ChainID 138?
**A**: Not yet via MetaMask Bridge. Use third-party bridges that support ChainID 138.
---
#### Q: Where can I buy tokens on ChainID 138?
**A**: On-ramp integration is in progress. Currently, you can:
1. Bridge tokens from other chains
2. Use DEX to swap tokens
3. Wait for on-ramp integration
---
#### Q: What tokens are available on ChainID 138?
**A**:
- **cUSDT** (Compliant Tether USD) - 6 decimals
- **cUSDC** (Compliant USD Coin) - 6 decimals
- **WETH** (Wrapped Ether) - 18 decimals
- **WETH10** (Wrapped Ether v10) - 18 decimals
- **LINK** (Chainlink Token) - 18 decimals
---
#### Q: How do I check my token balance?
**A**:
1. Connect to ChainID 138 in MetaMask
2. Tokens should appear automatically if added
3. Or click "Import tokens" to add manually
4. Check balance in MetaMask wallet
---
#### Q: Transactions are failing. What should I do?
**A**:
1. Check you're on ChainID 138
2. Check you have enough ETH for gas
3. Check token balance is sufficient
4. Try increasing gas limit
5. Check transaction on explorer: https://explorer.d-bis.org
---
#### Q: Where can I see my transaction history?
**A**:
1. Check MetaMask transaction history
2. Or visit explorer: https://explorer.d-bis.org
3. Enter your address in the search bar
4. View all transactions
---
## Troubleshooting Guide
### Issue: Cannot connect to network
**Solutions**:
1. Verify RPC URL is correct: `https://rpc.d-bis.org`
2. Check internet connection
3. Try secondary RPC: `https://rpc2.d-bis.org`
4. Clear MetaMask cache
5. Restart MetaMask
---
### Issue: Token balance shows as 0
**Solutions**:
1. Verify you're on ChainID 138
2. Check token address is correct
3. Verify token was added correctly
4. Check transaction history
5. Refresh MetaMask
---
### Issue: Transaction stuck/pending
**Solutions**:
1. Check network status
2. Try increasing gas price
3. Cancel and resubmit transaction
4. Check explorer for transaction status
5. Contact support if persists
---
### Issue: Decimals not showing
**Solutions**:
1. Remove token from MetaMask
2. Re-add token with decimals set to 6 (for cUSDT/cUSDC)
3. Or import updated token list
4. Clear MetaMask cache
---
## Support Process
### Tier 1: Self-Service
**Resources**:
- FAQ document
- Troubleshooting guide
- Video tutorials
- Documentation site
**Goal**: Users resolve issues independently
---
### Tier 2: Community Support
**Channels**:
- Discord #support
- GitHub Discussions
- Telegram group
**Goal**: Community helps users
---
### Tier 3: Direct Support
**Channels**:
- Support email
- Direct message (for critical issues)
- Scheduled calls (for complex issues)
**Goal**: Direct assistance for complex issues
---
## Support Metrics
### Track
- Number of support requests
- Response time
- Resolution time
- User satisfaction
- Common issues
### Goals
- Response time: < 24 hours
- Resolution time: < 48 hours
- User satisfaction: > 80%
- Self-service resolution: > 60%
---
## Support Team
### Roles
1. **Community Moderators**:
- Monitor support channels
- Answer common questions
- Escalate complex issues
2. **Technical Support**:
- Handle technical issues
- Debug problems
- Provide solutions
3. **Documentation Team**:
- Maintain documentation
- Create guides
- Update FAQs
---
## Training Materials
### For Support Team
1. **Network Overview**:
- ChainID 138 basics
- Network features
- Token information
2. **MetaMask Integration**:
- How integration works
- Common issues
- Solutions
3. **Troubleshooting**:
- Common problems
- Solutions
- Escalation process
---
## Feedback Collection
### Methods
1. **User Surveys**:
- Post-integration surveys
- Satisfaction surveys
- Feature request surveys
2. **Feedback Forms**:
- In-app feedback
- Website feedback form
- Email feedback
3. **Community Feedback**:
- GitHub Discussions
- Discord feedback channel
- Telegram group
---
## Documentation Updates
### Regular Updates
- Update FAQs based on common questions
- Update troubleshooting guide
- Update user guides
- Update developer docs
### Version Control
- Track documentation versions
- Maintain changelog
- Archive old versions
---
## Success Metrics
### Track
- Support request volume
- Resolution rate
- User satisfaction
- Documentation usage
- Community engagement
### Goals
- Reduce support requests over time
- Increase self-service resolution
- Improve user satisfaction
- Grow community engagement
---
**Last Updated**: 2026-01-26

269
docs/CONSENSYS_OUTREACH_PACKAGE.md Normal file
View File

@@ -0,0 +1,269 @@
# Consensys/MetaMask Outreach Package
Complete outreach package for requesting native MetaMask feature support for ChainID 138.
## Overview
This package contains all materials needed to contact Consensys/MetaMask for:
- Swaps integration
- Bridge integration
- On-ramp integration
- Native feature support
---
## Contact Information
### Consensys Business Development
- **Website**: https://consensys.io
- **Contact Form**: https://consensys.io/contact/
- **Email**: business@consensys.io (if available)
- **Twitter**: [@Consensys](https://twitter.com/Consensys)
- **LinkedIn**: https://www.linkedin.com/company/consensys
### MetaMask
- **Website**: https://metamask.io
- **Documentation**: https://docs.metamask.io
- **Support**: https://support.metamask.io
- **Developer Portal**: https://developers.metamask.io
---
## Outreach Email Template
### Subject Line
```
ChainID 138 Integration Request - DeFi Oracle Meta Mainnet
```
### Email Body
```
Dear Consensys Business Development Team,
We are reaching out to request native MetaMask feature support for ChainID 138 (DeFi Oracle Meta Mainnet).
**About ChainID 138:**
- Chain ID: 138 (0x8a)
- Network Name: DeFi Oracle Meta Mainnet
- Consensus: IBFT 2.0 (Istanbul BFT)
- RPC Endpoints: https://rpc.d-bis.org, https://rpc2.d-bis.org
- Block Explorer: https://explorer.d-bis.org
- Status: Live and operational
**Network Features:**
- ✅ Public RPC endpoints (HTTPS)
- ✅ Block explorer (Blockscout)
- ✅ Token contracts deployed (cUSDT, cUSDC, WETH, LINK)
- ✅ Oracle price feeds
- ✅ Stable network with high uptime
- ✅ Active development and community
**Integration Requests:**
1. **MetaMask Swaps**
- Enable token swaps on ChainID 138
- Support for cUSDT, cUSDC, WETH, LINK
- DEX integration ready
2. **MetaMask Bridge**
- Enable cross-chain bridging to ChainID 138
- Support bridging from Ethereum Mainnet and other chains
- Bridge infrastructure available
3. **MetaMask Buy/Sell**
- Enable on-ramp integration for ChainID 138
- Support fiat-to-crypto purchases
- Support crypto-to-fiat sales
**Network Statistics (2026-01-30):**
- Current Block: 1,581,000+
- Total Transactions: 13,156+
- Active Addresses: 94+
- Token Contracts: 11 deployed (Chain 138, Mainnet, ALL Mainnet)
- Network Uptime: >99%
- Average Block Time: 2 seconds
**Technical Details:**
- RPC: JSON-RPC 2.0 compliant
- WebSocket: Supported
- EIP-1559: Supported
- Gas Price: Dynamic
- Block Time: ~2 seconds
**Token List:**
- Official token list available
- All tokens verified on-chain
- Token metadata complete
- Logos hosted and accessible
**Compliance:**
- Regulatory compliant tokens (cUSDT, cUSDC)
- KYC/AML support available
- Travel rules compliance
**Partnership Opportunities:**
We are open to discussing partnership terms and integration requirements. We can provide:
- Technical support
- Documentation
- Testing resources
- Marketing support
**Next Steps:**
We would appreciate the opportunity to discuss integration requirements and timelines. Please let us know:
1. Required documentation
2. Technical requirements
3. Integration timeline
4. Partnership terms
Thank you for considering ChainID 138 for native MetaMask support.
Best regards,
[Your Name]
[Your Title]
[Your Organization]
[Contact Information]
```
---
## Supporting Documents
### 1. Network Information Sheet
**File**: `NETWORK_INFO_SHEET.md`
Contains:
- Network specifications
- RPC endpoint details
- Token information
- Explorer information
- Technical capabilities
### 2. Token List
**File**: `token-lists/lists/dbis-138.tokenlist.json`
- All tokens with metadata
- Verified on-chain
- Logo URLs included
- Follows Token Lists schema
### 3. Network Configuration
**File**: `metamask/network-metadata.json`
- Complete network configuration
- Ready for wallet_addEthereumChain
- All required fields present
### 4. Integration Status
**File**: `METAMASK_INTEGRATION_STATUS.md`
- Current integration status
- Completed features
- Pending features
- Roadmap
---
## Requirements Checklist
### For Swaps Integration
- [ ] Sufficient liquidity on ChainID 138
- [ ] DEX integration with aggregator
- [ ] Security audit completion
- [ ] Regulatory compliance
- [ ] User base and volume
- [ ] Token list submitted
- [ ] Network stability verified
### For Bridge Integration
- [ ] Bridge provider partnership
- [ ] Security audit completion
- [ ] Liquidity on both sides
- [ ] Monitoring and alerts
- [ ] Regulatory compliance
- [ ] Bridge contracts verified
### For On-Ramp Integration
- [ ] On-ramp partner integration
- [ ] Regulatory compliance
- [ ] KYC/AML compliance
- [ ] User experience optimization
- [ ] Payment processing
- [ ] Support infrastructure
---
## Timeline Estimates
Based on typical MetaMask integration timelines:
- **Swaps Integration**: 3-6 months
- **Bridge Integration**: 3-6 months
- **On-Ramp Integration**: 6-12 months
*Note: Timelines may vary based on requirements and partnership terms*
---
## Follow-Up Actions
1. **Initial Contact** (Week 1)
- Send outreach email
- Provide network information
- Request initial meeting
2. **Technical Review** (Weeks 2-4)
- Provide technical documentation
- Answer technical questions
- Demonstrate network capabilities
3. **Partnership Discussion** (Month 2)
- Discuss partnership terms
- Review requirements
- Agree on integration scope
4. **Integration Process** (Months 3-6+)
- Provide technical support
- Complete required audits
- Test integration
- Launch features
---
## Key Talking Points
1. **Network Stability**: High uptime, reliable infrastructure
2. **Token Support**: Compliant stablecoins (cUSDT, cUSDC)
3. **Developer Support**: Active development and documentation
4. **Community**: Growing user base
5. **Compliance**: Regulatory compliant tokens
6. **Technical Excellence**: Modern infrastructure, best practices
---
## Additional Resources
- **Explorer**: https://explorer.d-bis.org
- **Wallet Integration**: https://explorer.d-bis.org/wallet
- **Token List API**: https://explorer.d-bis.org/api/config/token-list
- **Network Config API**: https://explorer.d-bis.org/api/config/networks
- **Market Data API**: https://explorer.d-bis.org/api/market/chains
- **RPC Endpoints**:
- https://rpc-http-pub.d-bis.org
- https://rpc.d-bis.org
- https://rpc2.d-bis.org
- **Documentation**: Available in repository
- **Custom Snap**: Built and ready for testing
---
**Last Updated**: 2026-01-26

283
docs/DEX_INTEGRATION_GUIDE.md Normal file
View File

@@ -0,0 +1,283 @@
# DEX Integration Guide for ChainID 138
Complete guide for integrating DEX (Decentralized Exchange) functionality with MetaMask on ChainID 138.
## Overview
This guide covers DEX integration options for ChainID 138, enabling users to swap tokens directly in MetaMask.
## DEX Options
### Option 1: Partner with Existing DEX Providers
#### Recommended Providers
1. **Uniswap**
- Largest DEX by volume
- Well-established infrastructure
- V3 and V4 support
- **Contact**: https://uniswap.org
2. **1inch**
- DEX aggregator
- Best price routing
- Supports 100+ DEXs
- **Contact**: https://1inch.io
3. **0x Protocol**
- DEX aggregation protocol
- Open source
- Developer-friendly
- **Contact**: https://0x.org
4. **ParaSwap**
- DEX aggregator
- Gas optimization
- Multi-chain support
- **Contact**: https://paraswap.io
#### Integration Steps
1. **Contact DEX Provider**:
- Request ChainID 138 integration
- Provide network information
- Discuss liquidity requirements
2. **Liquidity Requirements**:
- Minimum liquidity per pair
- Liquidity distribution
- Liquidity incentives
3. **Integration Process**:
- Deploy DEX contracts on ChainID 138
- Configure DEX endpoints
- Add liquidity to pools
- Test swap functionality
- Launch DEX
### Option 2: Deploy Custom DEX
#### Architecture
```
┌─────────────┐
│ Users │
└──────┬──────┘
│
▼
┌─────────────┐
│ DEX Router │
└──────┬──────┘
│
├──► Pool 1 (cUSDT/cUSDC)
├──► Pool 2 (cUSDT/WETH)
├──► Pool 3 (cUSDC/WETH)
└──► Pool N (...)
```
#### Components
1. **DEX Router Contract**
- Routes swaps to best pool
- Handles multi-hop swaps
- Manages swap fees
2. **Liquidity Pools**
- AMM (Automated Market Maker) pools
- Constant product formula (x * y = k)
- Liquidity provider tokens
3. **Factory Contract**
- Creates new pools
- Manages pool registry
- Sets pool parameters
#### Implementation Steps
1. **Deploy DEX Contracts**:
```bash
# Deploy Factory
forge script script/dex/DeployFactory.s.sol --rpc-url $RPC_URL_138
# Deploy Router
forge script script/dex/DeployRouter.s.sol --rpc-url $RPC_URL_138
# Create Initial Pools
forge script script/dex/CreatePools.s.sol --rpc-url $RPC_URL_138
```
2. **Add Initial Liquidity**:
- Add liquidity to cUSDT/cUSDC pool
- Add liquidity to cUSDT/WETH pool
- Add liquidity to cUSDC/WETH pool
3. **Configure DEX**:
- Set swap fees
- Configure pool parameters
- Set up monitoring
4. **Security Audit**:
- Conduct security audit
- Fix identified issues
- Deploy audited contracts
### Option 3: Use DEX Aggregator
#### Aggregators
1. **1inch Aggregator**
- Best price routing
- Gas optimization
- Multi-DEX support
- **Integration**: https://docs.1inch.io
2. **0x API**
- DEX aggregation API
- Price discovery
- Order routing
- **Integration**: https://0x.org/docs/api
3. **ParaSwap API**
- DEX aggregation
- Best route finding
- Gas optimization
- **Integration**: https://developers.paraswap.network
## MetaMask Swaps Integration
### Requirements
1. **DEX Integration**:
- DEX deployed and operational
- Sufficient liquidity
- Security audit completed
2. **Token Support**:
- Supported tokens listed
- Token metadata complete
- Token logos available
3. **Liquidity**:
- Minimum liquidity per pair
- Liquidity distribution
- Liquidity incentives
4. **Consensys Approval**:
- Submit DEX for MetaMask approval
- Provide security documentation
- Complete integration review
### Integration Process
1. **Phase 1: DEX Setup** (Month 1-2)
- Deploy DEX contracts
- Add initial liquidity
- Test swap functionality
2. **Phase 2: Security Audit** (Month 2-3)
- Conduct security audit
- Fix identified issues
- Deploy audited contracts
3. **Phase 3: MetaMask Integration** (Month 3-6)
- Submit to MetaMask
- Complete integration review
- Test MetaMask integration
- Launch swaps
## DEX Configuration
### Supported Token Pairs
- **cUSDT/cUSDC**: Stablecoin pair
- **cUSDT/WETH**: Stablecoin/ETH pair
- **cUSDC/WETH**: Stablecoin/ETH pair
- **WETH/LINK**: ETH/Oracle pair
### Swap Fees
- **Trading Fee**: 0.3% (standard) or 0.05% (stablecoin pairs)
- **Protocol Fee**: 0.05% (to protocol treasury)
- **LP Fee**: 0.25% (to liquidity providers)
### Liquidity Requirements
- **Minimum**: $10,000 per pair
- **Recommended**: $100,000+ per pair
- **Optimal**: $1,000,000+ per pair
## Testing
### Test Scenarios
1. **Basic Swaps**:
- Swap cUSDT for cUSDC
- Swap cUSDC for WETH
- Swap WETH for cUSDT
- Verify swap amounts
2. **Edge Cases**:
- Swap minimum amount
- Swap maximum amount
- Swap with high slippage
- Swap with low liquidity
3. **Security**:
- Test price manipulation
- Test flash loan attacks
- Test reentrancy
- Test front-running
## Monitoring
### Metrics to Monitor
- Swap volume
- Swap success rate
- Liquidity levels
- Price impact
- Gas costs
- Security events
### Alerts
- Low liquidity warnings
- High slippage alerts
- Failed swaps
- Security incidents
## Documentation
### User Documentation
- How to swap tokens
- Swap fees and limits
- Slippage tolerance
- Troubleshooting guide
### Developer Documentation
- DEX API documentation
- Integration examples
- SDK documentation
- Contract addresses
## Support
### User Support
- Swap transaction issues
- Swap fee questions
- Slippage questions
- Troubleshooting
### Developer Support
- Integration help
- API questions
- Contract questions
- Testing support
---
**Last Updated**: 2026-01-26

435
docs/EXECUTING_NETWORK_TASKS.md Normal file
View File

@@ -0,0 +1,435 @@
# Executing Network-Dependent Tasks
**Date**: 2026-01-26
**Purpose**: Guide for executing all 22 network-dependent tasks
---
## Overview
This guide provides step-by-step instructions for executing all network-dependent tasks once network access is available.
**Total Network-Dependent Tasks**: **22**
---
## Prerequisites
### Required Infrastructure
1. **Network Access**:
- RPC endpoint for ChainID 138 accessible
- Block explorer access (https://explorer.d-bis.org)
- Network connectivity verified
2. **Deployer Wallet**:
- Wallet with sufficient ETH for gas fees
- Private key secured in `.env` file
- Backup of private key stored safely
3. **Environment Setup**:
- Foundry installed (`forge --version`)
- Node.js v18+ installed (`node --version`)
- Environment variables configured in `smom-dbis-138/.env`
### Environment Variables
Ensure these are set in `smom-dbis-138/.env`:
```bash
RPC_URL_138=https://rpc.d-bis.org
PRIVATE_KEY=your_private_key_here
SMART_ACCOUNT_FACTORY=0x... # Set after deployment
ENTRY_POINT=0x... # Set after deployment
```
---
## Execution Phases
### Phase 1: Contract Deployment (4 tasks)
#### Task 1.1: Deploy EntryPoint Contract
```bash
cd smom-dbis-138
forge script script/smart-accounts/DeploySmartAccountsKit.s.sol \
--rpc-url $RPC_URL_138 \
--broadcast \
--verify \
-vvv
```
**Record**: EntryPoint contract address
#### Task 1.2: Deploy AccountFactory Contract
```bash
# Same command as above (deploys both EntryPoint and AccountFactory)
# Record AccountFactory address from output
```
**Record**: AccountFactory contract address
#### Task 1.3: Deploy Paymaster Contract (Optional)
```bash
# If deploying Paymaster, update deployment script to include it
# Or deploy separately if needed
```
**Record**: Paymaster contract address (if deployed)
#### Task 1.4: Update Configuration
```bash
cd ../metamask-integration
./scripts/update-smart-accounts-config.sh --interactive
```
Enter the deployed contract addresses when prompted.
#### Task 1.5: Deploy AccountWalletRegistryExtended
```bash
cd ../smom-dbis-138
# Set environment variables first
export SMART_ACCOUNT_FACTORY=<AccountFactory address>
export ENTRY_POINT=<EntryPoint address>
forge script script/smart-accounts/DeployAccountWalletRegistryExtended.s.sol \
--rpc-url $RPC_URL_138 \
--broadcast \
--verify \
-vvv
```
**Record**: AccountWalletRegistryExtended contract address
---
### Phase 2: Unit Tests (5 tasks)
#### Task 2.1: Test Smart Account Creation
```bash
cd smom-dbis-138
forge test --match-path "test/smart-accounts/**" \
--match-test "test.*[Cc]reate.*[Aa]ccount" \
-vv \
--rpc-url $RPC_URL_138
```
#### Task 2.2: Test AccountWalletRegistry Linking
```bash
forge test --match-path "test/smart-accounts/**" \
--match-test "test.*[Ll]ink" \
-vv \
--rpc-url $RPC_URL_138
```
#### Task 2.3: Test Delegation Framework
```bash
forge test --match-path "test/smart-accounts/**" \
--match-test "test.*[Dd]elegation" \
-vv \
--rpc-url $RPC_URL_138
```
#### Task 2.4: Test Advanced Permissions
```bash
forge test --match-path "test/smart-accounts/**" \
--match-test "test.*[Pp]ermission" \
-vv \
--rpc-url $RPC_URL_138
```
#### Task 2.5: Test User Operations Batching
```bash
forge test --match-path "test/smart-accounts/**" \
--match-test "test.*[Bb]atch" \
-vv \
--rpc-url $RPC_URL_138
```
**Or run all unit tests at once**:
```bash
forge test --match-path "test/smart-accounts/**" -vv --rpc-url $RPC_URL_138
```
---
### Phase 3: Integration Tests (5 tasks)
#### Task 3.1: Test Smart Account + RailEscrowVault
```bash
cd metamask-integration
npm test -- --testNamePattern="RailEscrowVault"
```
#### Task 3.2: Test Smart Account + SettlementOrchestrator
```bash
npm test -- --testNamePattern="SettlementOrchestrator"
```
#### Task 3.3: Test Delegation + Payment Rails
```bash
npm test -- --testNamePattern="Payment.*Rail"
```
#### Task 3.4: Test Advanced Permissions + dApps
```bash
npm test -- --testNamePattern="dApp.*Permission"
```
#### Task 3.5: Test AccountWalletRegistry with EOA and Smart Accounts
```bash
npm test -- --testNamePattern="AccountWalletRegistry"
```
**Or run all integration tests at once**:
```bash
npm test
```
---
### Phase 4: End-to-End Tests (3 tasks)
#### Task 4.1: Test Complete Payment Rail Flow
```bash
npm run test:e2e -- --testNamePattern="Payment.*Rail.*Flow"
```
#### Task 4.2: Test Complete dApp Interaction Flow
```bash
npm run test:e2e -- --testNamePattern="dApp.*Flow"
```
#### Task 4.3: Test Hybrid EOA + Smart Account Flow
```bash
npm run test:e2e -- --testNamePattern="Hybrid.*Flow"
```
**Or run all E2E tests at once**:
```bash
npm run test:e2e
```
---
### Phase 5: Security Audit (1 task)
#### Task 5.1: Execute Security Audit
**This requires engaging a security audit firm.**
1. **Select Audit Firm**:
- Trail of Bits
- OpenZeppelin
- Consensys Diligence
- Other reputable firms
2. **Prepare Audit Package**:
- Contract source code
- Test suite
- Documentation
- Deployment addresses
3. **Engage Firm**:
- Contact firm
- Agree on scope and timeline
- Provide audit package
4. **Review Findings**:
- Review audit report
- Fix identified issues
- Re-audit if necessary
**See**: [Security Audit Preparation](./SECURITY_AUDIT_PREPARATION.md)
---
### Phase 6: Production Deployment (1 task)
#### Task 6.1: Deploy to Production Network
**Prerequisites**:
- All tests passing
- Security audit complete
- Production network access
- Production deployer wallet
```bash
cd metamask-integration
./scripts/deploy-smart-accounts-complete.sh
```
**Or manually**:
```bash
cd smom-dbis-138
forge script script/smart-accounts/DeploySmartAccountsKit.s.sol \
--rpc-url $PRODUCTION_RPC_URL \
--broadcast \
--verify \
-vvv
```
---
### Phase 7: User Acceptance Testing (1 task)
#### Task 7.1: Execute User Acceptance Testing
**Process**:
1. **Recruit Test Users**:
- Identify target users
- Provide test accounts
- Set up communication channel
2. **Define Test Scenarios**:
- Create Smart Account
- Link to fiat account
- Request delegation
- Use in dApp
- Test payment rails
3. **Collect Feedback**:
- User surveys
- Issue tracking
- Feedback sessions
4. **Document Issues**:
- Bug reports
- UX improvements
- Feature requests
5. **Fix and Iterate**:
- Address critical issues
- Implement improvements
- Re-test if needed
---
### Phase 8: Performance Testing (1 task)
#### Task 8.1: Execute Performance Testing on Live Network
```bash
cd metamask-integration
./scripts/performance-test.sh
```
**Metrics to Track**:
- Account creation time
- Delegation request time
- Transaction throughput
- Gas usage
- Network latency
**See**: [Performance Testing Guide](./PERFORMANCE_TESTING_GUIDE.md)
---
### Phase 9: Outreach (1 task)
#### Task 9.1: Create Video Tutorials
**Requirements**:
- Screen recording software
- Video editing tools
- Hosting platform (YouTube, etc.)
**Content Ideas**:
- Smart Account creation tutorial
- Delegation setup guide
- dApp integration walkthrough
- Payment rail integration demo
---
## Automated Execution
### Using the Execution Script
```bash
cd metamask-integration
# Deploy all contracts
./scripts/execute-network-tasks.sh deploy
# Run all tests
./scripts/execute-network-tasks.sh test
# Verify deployment
./scripts/execute-network-tasks.sh verify
# Execute everything
./scripts/execute-network-tasks.sh all
```
---
## Verification Checklist
After completing tasks, verify:
- [ ] All contracts deployed successfully
- [ ] Contract addresses recorded
- [ ] Configuration updated
- [ ] All unit tests passing
- [ ] All integration tests passing
- [ ] All E2E tests passing
- [ ] Security audit complete
- [ ] Production deployment successful
- [ ] UAT feedback collected
- [ ] Performance metrics documented
---
## Troubleshooting
### Common Issues
**Issue**: RPC connection failed
- **Solution**: Verify `RPC_URL_138` is correct and accessible
**Issue**: Insufficient gas
- **Solution**: Ensure deployer wallet has sufficient ETH
**Issue**: Contract verification failed
- **Solution**: Check block explorer API key and network connectivity
**Issue**: Tests failing
- **Solution**: Verify contracts are deployed and addresses are correct
---
## Resources
- [Deployment Checklist](../DEPLOYMENT_CHECKLIST.md)
- [Quick Start Deployment](./QUICK_START_DEPLOYMENT.md)
- [Network-Dependent Tasks List](../NETWORK_DEPENDENT_TASKS.md)
- [Security Audit Preparation](./SECURITY_AUDIT_PREPARATION.md)
- [Performance Testing Guide](./PERFORMANCE_TESTING_GUIDE.md)
---
**Last Updated**: 2026-01-26

191
docs/INCIDENT_RESPONSE.md Normal file
View File

@@ -0,0 +1,191 @@
# Incident Response Plan - Smart Accounts
**Date**: 2026-01-26
**Network**: ChainID 138 (SMOM-DBIS-138)
---
## Overview
This document outlines the incident response plan for Smart Accounts Kit integration.
---
## Incident Classification
### Severity Levels
**Critical**:
- Security breach
- Funds at risk
- System unavailable
**High**:
- Functionality degraded
- Performance issues
- Data integrity concerns
**Medium**:
- Minor functionality issues
- Performance degradation
- User experience issues
**Low**:
- Cosmetic issues
- Documentation issues
- Non-critical bugs
---
## Response Procedures
### Critical Incidents
**Immediate Actions**:
1. **Pause System**: Pause affected contracts if possible
2. **Assess Impact**: Determine scope of issue
3. **Notify Team**: Alert on-call team
4. **Investigate**: Identify root cause
5. **Mitigate**: Take immediate mitigation steps
**Communication**:
- Notify stakeholders immediately
- Provide status updates
- Document all actions
### High Priority Incidents
**Actions**:
1. **Assess Impact**: Determine affected users/features
2. **Investigate**: Identify root cause
3. **Mitigate**: Implement fixes
4. **Monitor**: Watch for resolution
**Communication**:
- Notify team
- Update status page
- Document issue
---
## Common Incidents
### Smart Account Creation Fails
**Symptoms**:
- Users cannot create accounts
- High error rate
- Transaction failures
**Response**:
1. Check RPC endpoint status
2. Check EntryPoint contract
3. Check AccountFactory contract
4. Check gas prices
5. Implement fix
### Delegation Not Working
**Symptoms**:
- Delegations not granted
- dApps cannot execute
- High failure rate
**Response**:
1. Check delegation framework
2. Check permissions
3. Check expiry times
4. Review recent changes
5. Implement fix
### Performance Degradation
**Symptoms**:
- Slow account creation
- High gas usage
- Timeout errors
**Response**:
1. Check network status
2. Check RPC performance
3. Review recent changes
4. Optimize if needed
5. Scale infrastructure
---
## Escalation Path
### Level 1: On-Call Engineer
- Initial response
- Basic troubleshooting
- Escalate if needed
### Level 2: Senior Engineer
- Complex issues
- Architecture decisions
- Escalate if needed
### Level 3: Engineering Lead
- Critical issues
- Strategic decisions
- External coordination
---
## Post-Incident
### Incident Review
1. **Root Cause Analysis**: Identify root cause
2. **Timeline**: Document incident timeline
3. **Impact Assessment**: Assess impact
4. **Lessons Learned**: Document learnings
5. **Action Items**: Create improvement tasks
### Documentation
- Incident report
- Root cause analysis
- Action items
- Timeline
---
## Prevention
### Monitoring
- Set up alerts
- Monitor metrics
- Track errors
- Review logs regularly
### Testing
- Regular testing
- Load testing
- Security testing
- Integration testing
### Documentation
- Keep documentation updated
- Document procedures
- Maintain runbooks
- Review regularly
---
## Resources
- [Troubleshooting Guide](./SMART_ACCOUNTS_TROUBLESHOOTING.md)
- [Monitoring Configuration](../config/monitoring-config.json)
- [Security Audit Preparation](./SECURITY_AUDIT_PREPARATION.md)
---
**Last Updated**: 2026-01-26

213
docs/INFRASTRUCTURE_SETUP.md Normal file
View File

@@ -0,0 +1,213 @@
# Infrastructure Setup Guide - Smart Accounts
**Date**: 2026-01-26
**Network**: ChainID 138 (SMOM-DBIS-138)
---
## Overview
This guide explains how to set up infrastructure for Smart Accounts Kit integration.
---
## Monitoring Setup
### 1. Prometheus Configuration
**File**: `config/monitoring-config.json`
**Setup**:
```bash
./scripts/setup-monitoring.sh
```
**Metrics**:
- Account creation rate
- Delegation requests
- Permission requests
- User operations
- Gas usage
### 2. Grafana Dashboards
**Create Dashboard**:
1. Import `config/monitoring-config.json`
2. Configure data source (Prometheus)
3. Create panels for each metric
**Panels**:
- Account creation rate (line chart)
- Delegation success rate (gauge)
- Gas usage (bar chart)
- Error rate (line chart)
---
## Alerting Setup
### Alert Rules
**High Gas Usage**:
- Threshold: > 500,000 gas
- Severity: Warning
- Action: Notify team
**Failed Operations**:
- Threshold: > 10 failures in 5 minutes
- Severity: Critical
- Action: Page on-call
**Delegation Expiry**:
- Threshold: Expiring in 7 days
- Severity: Info
- Action: Email notification
---
## Analytics Setup
### 1. Analytics Configuration
**File**: `config/analytics-config.json`
**Events Tracked**:
- Account creations
- Delegation requests
- Permission grants
- User operations
- Gas usage
### 2. Event Tracking
```typescript
// Track account creation
analytics.track('account_created', {
accountAddress: account.address,
owner: userAddress,
timestamp: Date.now(),
});
// Track delegation
analytics.track('delegation_granted', {
account: smartAccountAddress,
target: dAppAddress,
expiry: expiryTime,
});
```
---
## Backup and Recovery
### 1. Backup Setup
**Script**: `scripts/setup-backup-recovery.sh`
**Run**:
```bash
./scripts/setup-backup-recovery.sh
```
**Backup Schedule**:
- Daily backups of configuration
- Weekly backups of state
- Monthly full backups
### 2. Recovery Procedures
**Configuration Recovery**:
```bash
./backups/recover-smart-accounts-config.sh <timestamp>
```
**State Recovery**:
- Restore from blockchain (immutable)
- Re-sync from events
- Rebuild indexes
---
## CI/CD Setup
### GitHub Actions
**Workflow**: `.github/workflows/smart-accounts-ci.yml`
**Jobs**:
- Test contracts
- Test integration
- Lint contracts
- Security scan
- Verify deployment
**Run**:
- On push to main/develop
- On pull requests
- Manual trigger
---
## Security Setup
### 1. Access Control
- Role-based access control
- Multi-signature for admin functions
- Timelock for critical updates
### 2. Monitoring
- Security event monitoring
- Anomaly detection
- Alert on suspicious activity
### 3. Audit Logging
- Log all admin actions
- Log all configuration changes
- Log all security events
---
## Performance Setup
### 1. Performance Monitoring
- Track response times
- Monitor gas usage
- Track success rates
### 2. Load Testing
**Script**: `scripts/performance-test.sh`
**Run**:
```bash
./scripts/performance-test.sh
```
**Metrics**:
- Account creation time
- Delegation time
- Batch operation time
---
## Documentation
### Setup Guides
- [Monitoring Setup](./scripts/setup-monitoring.sh)
- [Backup Setup](./scripts/setup-backup-recovery.sh)
- [Performance Testing](./docs/PERFORMANCE_TESTING_GUIDE.md)
### Configuration Files
- `config/monitoring-config.json`
- `config/analytics-config.json`
- `config/smart-accounts-config.json`
---
**Last Updated**: 2026-01-26

142
docs/INTEGRATION_AND_TESTING.md Normal file
View File

@@ -0,0 +1,142 @@
# Integration and Testing
How to build, integrate, and test the MetaMask dual-chain provider, explorer config, token-aggregation API, and Chain 138 Snap. **Default package manager: pnpm.**
---
## Run all (pnpm)
From the repo root or `metamask-integration/`:
```bash
cd metamask-integration
pnpm run run-all
```
Runs: (1) full integration script (provider test + config validation), (2) token-aggregation `pnpm install` + `pnpm run build`, (3) explorer frontend `pnpm install` + `pnpm run build`, (4) Chain 138 Snap install + build (Snap template uses yarn internally).
---
## 1. Provider (Node) integration test
From the repo root (or `metamask-integration/`):
```bash
cd metamask-integration/provider
pnpm exec node test-integration.mjs
# or: node test-integration.mjs
```
Tests chains, tokens, wallet exports, and oracles without `window.ethereum`. Expect: **4 passed, 0 failed**.
---
## 2. Full integration script
Runs provider test + validates explorer config JSONs + optional Explorer API and token-aggregation API:
```bash
cd metamask-integration
pnpm run test:integration
# or: ./scripts/integration-test-all.sh
```
**Optional env (for live API checks):**
- `EXPLORER_API_URL` – e.g. `http://localhost:8080` (explorer backend)
- `TOKEN_AGGREGATION_URL` – e.g. `http://localhost:3000` (token-aggregation service)
Config files validated from repo: `docs/04-configuration/metamask/DUAL_CHAIN_NETWORKS.json`, `DUAL_CHAIN_TOKEN_LIST.tokenlist.json`.
---
## 3. Explorer API (config endpoints)
Explorer backend serves:
- `GET /api/config/networks` – Chain 138 + Ethereum Mainnet + ALL Mainnet params
- `GET /api/config/token-list` – Uniswap token list format
To test against a running explorer:
```bash
export EXPLORER_API_URL=http://localhost:8080
./scripts/integration-test-all.sh
```
Explorer backend requires DB; see `explorer-monorepo/backend/` for build/run.
---
## 4. Token-aggregation API
Token-aggregation service (Chain 138 + ALL Mainnet) exposes:
**Note:** The service may have existing TypeScript build issues in `canonical-tokens.ts`; the REST API is documented and can be tested when the service is run (e.g. via Docker or with DB).
- `GET /api/v1/chains` – supported chains
- `GET /api/v1/tokens?chainId=138` – tokens and market data
- See `smom-dbis-138/services/token-aggregation/docs/REST_API_REFERENCE.md`
To test when the service is running (with DB):
```bash
export TOKEN_AGGREGATION_URL=http://localhost:3000
./scripts/integration-test-all.sh
```
---
## 5. Provider E2E (manual, browser)
Open `metamask-integration/examples/provider-e2e.html` **via a local server** (e.g. `npx serve metamask-integration/examples` or your app) with MetaMask installed.
- **Add chains** – adds Chain 138, Ethereum Mainnet, ALL Mainnet
- **Switch chain** – 138 / 1 / 651940
- **List tokens** – tokens from provider for current chain
- **ETH/USD price** – oracle price (requires ethers; loads from esm.sh if needed)
---
## 6. Chain 138 Snap
Snap provides:
- `get_chain138_config` – Chain 138 params for `wallet_addEthereumChain`
- `get_chain138_market_chains` – fetches `GET {apiBaseUrl}/api/v1/chains` (pass token-aggregation base URL)
- `hello` – demo dialog
**Build and run (from repo root):**
```bash
cd metamask-integration/chain138-snap
yarn install
yarn build
yarn start
```
Then install the Snap in MetaMask Flask using the provided site (e.g. `http://localhost:8000`). Invoke from a dapp:
```js
await ethereum.request({
method: 'wallet_invokeSnap',
params: {
snapId: 'YOUR_SNAP_ID',
request: { method: 'get_chain138_config' },
},
});
```
---
## Summary
| Item | Command / location (pnpm default) |
|------|------------------------------------|
| **Run all** | `cd metamask-integration && pnpm run run-all` |
| Provider test | `cd provider && pnpm exec node test-integration.mjs` |
| Full integration | `pnpm run test:integration` or `./scripts/integration-test-all.sh` |
| Explorer config | Validated by script; optional `EXPLORER_API_URL` |
| Token-aggregation | `cd smom-dbis-138/services/token-aggregation && pnpm install && pnpm run build`; optional `TOKEN_AGGREGATION_URL` in script |
| Provider E2E | Serve `examples/provider-e2e.html`, use MetaMask |
| Snap | `chain138-snap`: pnpm install, pnpm run build, pnpm run start (template uses yarn internally); install in Flask |

288
docs/METAMASK_EMBEDDED_WALLETS_GUIDE.md Normal file
View File

@@ -0,0 +1,288 @@
# MetaMask Embedded Wallets Integration Guide
**Date**: 2026-01-26
**Network**: ChainID 138 (DeFi Oracle Meta Mainnet)
**Reference**: [MetaMask Embedded Wallets Documentation](https://docs.metamask.io/embedded-wallets/dashboard/chains-and-networks/)
---
## Overview
MetaMask Embedded Wallets (powered by Web3Auth) allows developers to embed wallet functionality directly into their dApps without requiring users to install the MetaMask extension. This guide covers integration for ChainID 138.
---
## Key Differences: Embedded Wallets vs Extension
| Feature | MetaMask Extension | Embedded Wallets |
|---------|-------------------|------------------|
| **Installation** | Browser extension required | No installation needed |
| **User Experience** | External wallet | Embedded in dApp |
| **Configuration** | Manual network addition | Dashboard-based configuration |
| **Authentication** | Extension-based | Social/Email/Phone login |
| **Use Case** | Power users | Mass adoption |
---
## Dashboard Configuration
### Step 1: Access MetaMask Embedded Wallets Dashboard
1. Go to [MetaMask Developer Dashboard](https://dashboard.metamask.io)
2. Create a new project or select existing project
3. Navigate to **Configuration → Chains and Networks**
### Step 2: Add ChainID 138 as Custom Network
According to the [MetaMask documentation](https://docs.metamask.io/embedded-wallets/dashboard/chains-and-networks/#adding-custom-networks), add the following:
#### Required Fields:
- **Chain ID**: `138` (or `0x8a` in hex)
- **Currency Symbol**: `ETH`
- **Block Explorer URL**: `https://explorer.d-bis.org`
- **Namespace**: `eip155` (for EVM-compatible chains)
- **RPC URL**: `https://rpc.d-bis.org` (or `https://rpc2.d-bis.org`)
#### Network Configuration:
```json
{
"chainId": 138,
"chainName": "DeFi Oracle Meta Mainnet",
"currencySymbol": "ETH",
"blockExplorerUrl": "https://explorer.d-bis.org",
"namespace": "eip155",
"rpcUrl": "https://rpc.d-bis.org"
}
```
### Step 3: Configure Network Settings
1. **Enable Network**: Toggle ChainID 138 to enabled
2. **Set as Default** (optional): Make ChainID 138 the default network
3. **Testnet/Mainnet**: Mark as Mainnet
4. **Save Configuration**: Click "Save & Publish"
---
## Customization Configuration
### Branding Setup
Navigate to **Configuration → Customization → Branding**:
#### Brand Logo
- **Upload Logo**: Upload ChainID 138 network logo
- **Recommended**: PNG format, 512x512px
- **Use as Loader**: Enable to show logo during loading
#### Application Name
- **Name**: "DeFi Oracle Meta Mainnet" or "ChainID 138"
- **Used in**: Email templates, system communications
#### Terms and Privacy
- **Terms URL**: Link to terms of service
- **Privacy Policy URL**: Link to privacy policy
#### Default Language
- **Language**: English (or preferred language)
### Theme Configuration
Navigate to **Configuration → Customization → Theme and Colors**:
#### Mode Selection
- **Light Mode**: Light theme
- **Dark Mode**: Dark theme
- **Auto Mode**: Adapts to user's system preference (recommended)
#### Color Scheme
- **Primary Color**: Network brand color (e.g., `#667eea`)
- **On Primary Color**: Text color on primary background (e.g., `#ffffff`)
### Login Modal Configuration
Navigate to **Configuration → Customization → Login Modal**:
#### Design Options
- **Modal Appearance**:
- **Embedded Widget**: Login UI embedded in page
- **Modal Widget**: Pop-up modal (recommended)
- **Logo Alignment**: Center or Left
- **Border Radius**: Small, Medium, or Large
- **Border Radius Type**: Pill, Rounded, or Square
#### Authentication Order
- **Arrange Login Methods**: Drag and drop to reorder
- Social logins (Google, Twitter, etc.)
- Email/Phone
- External wallets (MetaMask extension, WalletConnect)
#### External Wallets
- **Show Installed Wallets**: Enable to detect MetaMask extension
- **Number of Wallets**: Configure how many to display
---
## SDK Integration
### React Integration
```typescript
import { Web3Auth } from '@web3auth/modal';
import { CHAIN_NAMESPACES } from '@web3auth/base';
const web3auth = new Web3Auth({
clientId: 'YOUR_CLIENT_ID', // From dashboard
chainConfig: {
chainNamespace: CHAIN_NAMESPACES.EIP155,
chainId: '0x8a', // 138 in hex
rpcTarget: 'https://rpc.d-bis.org',
displayName: 'DeFi Oracle Meta Mainnet',
blockExplorerUrl: 'https://explorer.d-bis.org',
ticker: 'ETH',
tickerName: 'Ether',
},
});
// Initialize
await web3auth.init();
// Connect
await web3auth.connect();
```
### Vue Integration
```typescript
import { Web3Auth } from '@web3auth/modal';
import { CHAIN_NAMESPACES } from '@web3auth/base';
export default {
data() {
return {
web3auth: null,
provider: null,
};
},
async mounted() {
this.web3auth = new Web3Auth({
clientId: 'YOUR_CLIENT_ID',
chainConfig: {
chainNamespace: CHAIN_NAMESPACES.EIP155,
chainId: '0x8a',
rpcTarget: 'https://rpc.d-bis.org',
displayName: 'DeFi Oracle Meta Mainnet',
blockExplorerUrl: 'https://explorer.d-bis.org',
ticker: 'ETH',
tickerName: 'Ether',
},
});
await this.web3auth.init();
},
methods: {
async connect() {
this.provider = await this.web3auth.connect();
},
},
};
```
### JavaScript Integration
```javascript
import { Web3Auth } from '@web3auth/modal';
import { CHAIN_NAMESPACES } from '@web3auth/base';
const web3auth = new Web3Auth({
clientId: 'YOUR_CLIENT_ID',
chainConfig: {
chainNamespace: CHAIN_NAMESPACES.EIP155,
chainId: '0x8a',
rpcTarget: 'https://rpc.d-bis.org',
displayName: 'DeFi Oracle Meta Mainnet',
blockExplorerUrl: 'https://explorer.d-bis.org',
ticker: 'ETH',
tickerName: 'Ether',
},
});
await web3auth.init();
const provider = await web3auth.connect();
```
---
## Token Configuration
### Adding Tokens to Embedded Wallets
Tokens are automatically detected from the token list configured in the dashboard. Ensure your token list includes:
1. **Token Address**: Contract address on ChainID 138
2. **Token Symbol**: Display symbol (e.g., cUSDT, cUSDC)
3. **Token Name**: Full name (e.g., "Compliant Tether USD")
4. **Decimals**: Token decimals (6 for cUSDT/cUSDC, 18 for WETH)
5. **Logo URL**: Accessible logo URL
### Token List Configuration
The token list should be hosted and accessible. See [Token List Hosting Guide](./METAMASK_TOKEN_LIST_HOSTING.md) for details.
---
## Benefits of Embedded Wallets
### For Developers
- ✅ **No SDK Changes**: Network config via dashboard
- ✅ **Instant Updates**: Changes take effect immediately
- ✅ **Environment-Specific**: Different configs for dev/prod
- ✅ **Testnet Support**: Easy switching between networks
### For Users
- ✅ **No Extension Required**: Works in any browser
- ✅ **Social Login**: Login with Google, Twitter, etc.
- ✅ **Email/Phone Login**: Traditional authentication
- ✅ **Seamless Experience**: Embedded in dApp
---
## Integration Checklist
- [ ] Create MetaMask Embedded Wallets project
- [ ] Add ChainID 138 as custom network in dashboard
- [ ] Configure branding (logo, colors, theme)
- [ ] Configure login modal appearance
- [ ] Set up authentication methods
- [ ] Configure external wallet detection
- [ ] Add token list URL
- [ ] Test embedded wallet connection
- [ ] Test token display
- [ ] Test transactions
---
## Next Steps
1. **Get Client ID**: Register project in MetaMask dashboard
2. **Configure Network**: Add ChainID 138 via dashboard
3. **Integrate SDK**: Add Web3Auth SDK to your dApp
4. **Test Integration**: Test wallet connection and transactions
5. **Deploy**: Deploy to production
---
## Resources
- [MetaMask Embedded Wallets Docs](https://docs.metamask.io/embedded-wallets/)
- [Chains and Networks Configuration](https://docs.metamask.io/embedded-wallets/dashboard/chains-and-networks/)
- [Customization Guide](https://docs.metamask.io/embedded-wallets/dashboard/customization/)
- [Web3Auth Documentation](https://web3auth.io/docs/)
---
**Last Updated**: 2026-01-26

32
docs/METAMASK_TOKEN_LIST.json
View File

@@ -2,10 +2,10 @@
"name": "SMOM-DBIS-138 Token List",
"version": {
"major": 1,
"minor": 1,
"minor": 2,
"patch": 0
},
"timestamp": "2025-12-22T17:45:00.000Z",
"timestamp": "2026-01-26T00:00:00.000Z",
"tokens": [
{
"chainId": 138,
@@ -13,7 +13,7 @@
"name": "ETH/USD Price Feed",
"symbol": "ETH-USD",
"decimals": 8,
"logoURI": "https://raw.githubusercontent.com/ethereum/ethereum.org/main/static/images/eth-diamond-black.png"
"logoURI": "https://ipfs.io/ipfs/QmPZuycjyJEe2otREuQ5HirvPJ8X6Yc6MBtwz1VhdD79pY"
},
{
"chainId": 138,
@@ -21,15 +21,31 @@
"name": "Wrapped Ether",
"symbol": "WETH",
"decimals": 18,
"logoURI": "https://raw.githubusercontent.com/ethereum/ethereum.org/main/static/images/eth-diamond-black.png"
"logoURI": "https://ipfs.io/ipfs/Qma3FKtLce9MjgJgWbtyCxBiPjJ6xi8jGWUSKNS5Jc2ong"
},
{
"chainId": 138,
"address": "0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f",
"address": "0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9F",
"name": "Wrapped Ether v10",
"symbol": "WETH10",
"symbol": "WETH",
"decimals": 18,
"logoURI": "https://raw.githubusercontent.com/ethereum/ethereum.org/main/static/images/eth-diamond-black.png"
"logoURI": "https://ipfs.io/ipfs/QmanDFPHxnbKd6SSNzzXHf9GbpL9dLXSphxDZSPPYE6ds4"
},
{
"chainId": 138,
"address": "0x93E66202A11B1772E55407B32B44e5Cd8eda7f22",
"name": "Compliant Tether USD",
"symbol": "cUSDT",
"decimals": 6,
"logoURI": "https://ipfs.io/ipfs/QmRfhPs9DcyFPpGjKwF6CCoVDWUHSxkQR34n9NK7JSbPCP"
},
{
"chainId": 138,
"address": "0xf22258f57794CC8E06237084b353Ab30fFfa640b",
"name": "Compliant USD Coin",
"symbol": "cUSDC",
"decimals": 6,
"logoURI": "https://ipfs.io/ipfs/QmNPq4D5JXzurmi9jAhogVMzhAQRk1PZ1r9H3qQUV9gjDm"
}
]
}
}

26
docs/METAMASK_WETH9_FIX_INSTRUCTIONS.md
View File

@@ -42,7 +42,20 @@ Since the contract's `decimals()` function is incorrect, you need to manually sp
4. **Verify**
- The token should now display as "6 WETH" instead of "6,000,000,000.0T WETH"
- You may need to remove the old token entry first if it exists
- **Note:** MetaMask only lets you **hide** an asset, not remove it. If WETH already shows the wrong amount (e.g. "500.00T WETH"): open the asset → ⋮ menu → **Hide WETH**, then add the token again via the explorer’s "Add to wallet" button or manual import above with **Decimals: 18**. The new entry will use the correct decimals.
---
## 📱 MetaMask: Hide, then re-add with correct decimals
MetaMask does not offer "Remove token" — only **Hide [asset]** (⋮ menu on the token). To fix a wrong WETH display (e.g. "500.00T WETH" instead of "500 WETH"):
1. Open the WETH asset → tap the **⋮** menu → **Hide WETH**.
2. Add the token again so MetaMask gets **decimals: 18**:
- **Option A:** Go to https://explorer.d-bis.org/weth , connect MetaMask, and click the **wallet icon** next to the WETH9 contract. Confirm "Add token." The explorer sends decimals 18 and symbol WETH.
- **Option B:** In MetaMask, Import tokens → Custom token: Address `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2`, Symbol **WETH**, **Decimals 18** → Add.
The (re-)added token should then show the correct balance (e.g. 500 WETH).
---
@@ -65,6 +78,17 @@ If you have access to host a token list JSON file:
---
## 🌐 Explorer "Add to wallet" (same as MetaMask display)
The **SolaceScanScout explorer** (https://explorer.d-bis.org) adds WETH9 and WETH10 to MetaMask with **decimals: 18** and **symbol: WETH** when you click the wallet icon next to a token (WETH page, Tokens list, or token detail). So MetaMask will display balances the same way as the explorer (e.g. "100 WETH", not "100T" or raw wei).
- **WETH page** (Tools → WETH): wallet icon next to each contract address.
- **Tokens list** and **token detail**: wallet icon to add that token with correct decimals and symbol.
Our token lists (`METAMASK_TOKEN_LIST.json`, `config/token-list.json`, provider token list) also use **symbol: WETH** and **decimals: 18** for both WETH9 and WETH10 so any app using these lists will show the same as the explorer.
---
## 📊 Verification
After fixing, verify the display:

155
docs/MIGRATION_GUIDE.md Normal file
View File

@@ -0,0 +1,155 @@
# Migration Guide - EOA to Smart Accounts
**Date**: 2026-01-26
**Network**: ChainID 138 (SMOM-DBIS-138)
---
## Overview
This guide explains how to migrate from EOA (Externally Owned Accounts) to Smart Accounts for existing users.
---
## Migration Scenarios
### Scenario 1: Keep EOA, Add Smart Account
**Use Case**: User wants both EOA and Smart Account
**Steps**:
1. Create Smart Account
2. Link Smart Account to same fiat account
3. Use EOA for payment rails
4. Use Smart Account for dApp interactions
**Benefits**:
- Backward compatible
- Gradual migration
- No disruption
---
### Scenario 2: Full Migration to Smart Account
**Use Case**: User wants to fully migrate to Smart Account
**Steps**:
1. Create Smart Account
2. Transfer assets from EOA to Smart Account
3. Link Smart Account to fiat account
4. Update all references to use Smart Account
5. Deactivate EOA link (optional)
**Benefits**:
- Full Smart Account features
- Enhanced security
- Delegation support
---
## Migration Process
### Step 1: Create Smart Account
```typescript
import { SmartAccountsKit } from '@metamask/smart-accounts-kit';
const kit = new SmartAccountsKit({ ... });
const smartAccount = await kit.createAccount({
owner: userEOAAddress,
});
```
### Step 2: Link to Fiat Account
```typescript
// Contact account manager to link Smart Account
// Provide: Smart Account address, fiat account reference
```
### Step 3: Transfer Assets (if migrating)
```typescript
// Transfer tokens from EOA to Smart Account
await token.transfer(smartAccountAddress, amount);
```
### Step 4: Update References
- Update dApp configurations
- Update payment rail references
- Update delegation targets
---
## Migration Checklist
### Pre-Migration
- [ ] Review Smart Account features
- [ ] Understand delegation and permissions
- [ ] Backup current configuration
- [ ] Test on testnet (if available)
### Migration
- [ ] Create Smart Account
- [ ] Link to fiat account
- [ ] Transfer assets (if migrating)
- [ ] Update configurations
- [ ] Test functionality
### Post-Migration
- [ ] Verify Smart Account works
- [ ] Test delegation (if needed)
- [ ] Test permissions (if needed)
- [ ] Monitor for issues
---
## Rollback Procedure
### If Issues Occur
1. **Keep EOA Active**: Don't deactivate EOA link
2. **Use EOA**: Switch back to EOA for operations
3. **Investigate**: Identify and fix issues
4. **Retry**: Try migration again after fixes
---
## Best Practices
### 1. Gradual Migration
- Start with Smart Account for new features
- Keep EOA for existing operations
- Gradually migrate operations
### 2. Testing
- Test on testnet first
- Test with small amounts
- Verify all functionality
### 3. Documentation
- Document migration steps
- Keep rollback plan ready
- Monitor for issues
---
## Support
For migration assistance:
1. Review this guide
2. Check troubleshooting guide
3. Contact support team
---
**Last Updated**: 2026-01-26

344
docs/ON_RAMP_INTEGRATION_GUIDE.md Normal file
View File

@@ -0,0 +1,344 @@
# On-Ramp Integration Guide for ChainID 138
Complete guide for integrating on-ramp (buy/sell) functionality with MetaMask on ChainID 138.
## Overview
This guide covers on-ramp integration options for ChainID 138, enabling users to buy and sell tokens with fiat currency directly in MetaMask.
## On-Ramp Providers
### Recommended Providers
1. **MoonPay**
- Leading on-ramp provider
- Supports 100+ countries
- Multiple payment methods
- **Contact**: https://www.moonpay.com/business
- **Integration**: https://developers.moonpay.com
2. **Ramp Network**
- European-focused
- Fast KYC process
- Competitive fees
- **Contact**: https://ramp.network
- **Integration**: https://docs.ramp.network
3. **Transak**
- Global coverage
- Multiple payment methods
- Developer-friendly
- **Contact**: https://transak.com
- **Integration**: https://docs.transak.com
4. **Wyre**
- US-focused
- Bank transfers
- ACH support
- **Contact**: https://www.sendwyre.com
- **Integration**: https://docs.sendwyre.com
5. **Banxa**
- Global coverage
- Multiple payment methods
- Fast processing
- **Contact**: https://banxa.com
- **Integration**: https://docs.banxa.com
## Integration Process
### Step 1: Choose Provider
Considerations:
- **Geographic Coverage**: Which countries are supported?
- **Payment Methods**: Credit card, bank transfer, etc.
- **Fees**: Transaction fees and limits
- **KYC Requirements**: KYC process and requirements
- **Integration Complexity**: Ease of integration
- **Support**: Developer and user support
### Step 2: Partner with Provider
1. **Contact Provider**:
- Request ChainID 138 integration
- Provide network information
- Discuss partnership terms
2. **Requirements**:
- Network information
- Token information
- Compliance documentation
- Business information
3. **Agreement**:
- Partnership terms
- Fee structure
- Integration timeline
- Support agreement
### Step 3: Technical Integration
#### MoonPay Integration Example
```javascript
// MoonPay Widget Integration
import { MoonPayBuyWidget } from '@moonpay/moonpay-js';
const moonPay = new MoonPayBuyWidget({
apiKey: 'YOUR_API_KEY',
environment: 'production',
variant: 'overlay',
baseCurrencyCode: 'usd',
baseCurrencyAmount: '100',
defaultCurrencyCode: 'eth',
walletAddress: userAddress,
walletAddresses: {
eth: userAddress,
// Add ChainID 138 address
},
onClose: () => {
console.log('Widget closed');
},
onComplete: (data) => {
console.log('Transaction complete', data);
},
});
moonPay.show();
```
#### Ramp Integration Example
```javascript
// Ramp Widget Integration
import { RampInstant } from '@ramp-network/ramp-instant';
const ramp = new RampInstant({
hostAppName: 'Your App',
hostLogoUrl: 'https://your-app.com/logo.png',
variant: 'auto',
defaultAsset: 'ETH_138', // ChainID 138 ETH
userAddress: userAddress,
onClose: () => {
console.log('Widget closed');
},
onPurchaseCreated: (purchase) => {
console.log('Purchase created', purchase);
},
});
```
### Step 4: Configure Network
1. **Add ChainID 138 to Provider**:
- Provide network configuration
- Configure RPC endpoints
- Set up token support
2. **Token Configuration**:
- Add supported tokens
- Configure token metadata
- Set up token logos
3. **Testing**:
- Test buy flow
- Test sell flow
- Test error handling
## Supported Tokens
### Buy (Fiat → Crypto)
- **ETH**: Native currency
- **cUSDT**: Compliant Tether USD
- **cUSDC**: Compliant USD Coin
- **WETH**: Wrapped Ether
- **LINK**: Chainlink Token
### Sell (Crypto → Fiat)
- **ETH**: Native currency
- **cUSDT**: Compliant Tether USD
- **cUSDC**: Compliant USD Coin
## Payment Methods
### Supported Methods
1. **Credit/Debit Cards**:
- Visa, Mastercard, Amex
- Instant processing
- Higher fees
2. **Bank Transfers**:
- ACH (US)
- SEPA (Europe)
- Lower fees
- Slower processing
3. **Apple Pay / Google Pay**:
- Mobile payments
- Fast processing
- Higher fees
4. **Crypto Payments**:
- Pay with other cryptocurrencies
- Instant processing
- Lower fees
## Fees and Limits
### Typical Fees
- **Credit Card**: 3-5%
- **Bank Transfer**: 1-2%
- **Apple Pay / Google Pay**: 3-5%
- **Crypto Payment**: 0.5-1%
### Typical Limits
- **Minimum**: $10-50
- **Maximum (Daily)**: $1,000-10,000
- **Maximum (Monthly)**: $10,000-100,000
- **KYC Required**: Varies by amount
## KYC/AML Requirements
### KYC Levels
1. **Level 1 (No KYC)**:
- Small amounts only
- Limited features
- Basic verification
2. **Level 2 (Basic KYC)**:
- Email verification
- Phone verification
- ID verification
3. **Level 3 (Full KYC)**:
- Full identity verification
- Address verification
- Enhanced due diligence
### Compliance
- **KYC**: Know Your Customer
- **AML**: Anti-Money Laundering
- **Sanctions**: Sanctions screening
- **Regulatory**: Regulatory compliance
## MetaMask Integration
### Requirements
1. **On-Ramp Provider Partnership**:
- Partner with on-ramp provider
- Complete integration
- Test functionality
2. **Consensys Approval**:
- Submit on-ramp for MetaMask approval
- Provide compliance documentation
- Complete integration review
3. **Compliance**:
- KYC/AML compliance
- Regulatory compliance
- Security compliance
### Integration Process
1. **Phase 1: Provider Integration** (Month 1-2)
- Partner with provider
- Complete technical integration
- Test buy/sell flows
2. **Phase 2: Compliance** (Month 2-3)
- Complete KYC/AML setup
- Regulatory compliance
- Security review
3. **Phase 3: MetaMask Integration** (Month 3-6)
- Submit to MetaMask
- Complete integration review
- Test MetaMask integration
- Launch on-ramp
## Testing
### Test Scenarios
1. **Buy Flow**:
- Buy ETH with credit card
- Buy cUSDT with bank transfer
- Verify tokens received
- Test error handling
2. **Sell Flow**:
- Sell ETH for fiat
- Sell cUSDT for fiat
- Verify fiat received
- Test error handling
3. **Edge Cases**:
- Minimum amount
- Maximum amount
- Failed payments
- Refunds
## Monitoring
### Metrics to Monitor
- Buy/sell volume
- Success rate
- Average transaction time
- Fee collection
- User complaints
- Security events
### Alerts
- Failed transactions
- High failure rate
- Security incidents
- Compliance issues
## Documentation
### User Documentation
- How to buy tokens
- How to sell tokens
- Payment methods
- Fees and limits
- KYC process
- Troubleshooting guide
### Developer Documentation
- On-ramp API documentation
- Integration examples
- SDK documentation
- Webhook documentation
## Support
### User Support
- Buy/sell transaction issues
- Payment method questions
- KYC questions
- Troubleshooting
### Developer Support
- Integration help
- API questions
- Webhook questions
- Testing support
---
**Last Updated**: 2026-01-26

193
docs/OUTREACH_MATERIALS.md Normal file
View File

@@ -0,0 +1,193 @@
# Outreach Materials - Smart Accounts
**Date**: 2026-01-26
**Network**: ChainID 138 (SMOM-DBIS-138)
---
## Overview
This document provides outreach materials for promoting Smart Accounts on ChainID 138.
---
## Key Messages
### For Users
**Headline**: "Enhanced Wallet Experience with Smart Accounts"
**Key Points**:
- Programmable account behavior
- Delegation for dApps
- Advanced permissions
- Batch operations
- Gas abstraction (if enabled)
**Benefits**:
- Better security
- Enhanced control
- Improved UX
- Lower gas costs (with batching)
---
### For Developers
**Headline**: "Build Better dApps with Smart Accounts"
**Key Points**:
- Easy integration
- Comprehensive SDK
- Complete documentation
- Full feature support
**Benefits**:
- Execute on behalf of users
- Fine-grained permissions
- Better user experience
- Reduced friction
---
## Social Media Posts
### Twitter/X
**Post 1**:
```
🚀 Smart Accounts are now available on ChainID 138!
✨ Programmable accounts
🔐 Enhanced security
⚡ Better UX
💰 Lower gas costs
Get started: [link to docs]
```
**Post 2**:
```
💡 Build better dApps with Smart Accounts on ChainID 138
✅ Execute on behalf of users
✅ Fine-grained permissions
✅ Batch operations
✅ Complete SDK
Developer guide: [link]
```
---
## Blog Post Outline
### Title
"Introducing Smart Accounts on ChainID 138: Enhanced Wallet Experience"
### Sections
1. **Introduction**
- What are Smart Accounts
- Why they matter
2. **Features**
- Delegation
- Advanced Permissions
- Batch Operations
- Gas Abstraction
3. **Use Cases**
- Payment rails
- dApp interactions
- DeFi protocols
4. **Getting Started**
- Quick start guide
- Examples
- Documentation
5. **Conclusion**
- Benefits summary
- Call to action
---
## Press Release Template
### Headline
"ChainID 138 Launches Smart Accounts Integration with MetaMask"
### Body
ChainID 138 (SMOM-DBIS-138) today announced the integration of MetaMask Smart Accounts Kit, enabling programmable account behavior and enhanced user experience.
**Key Features**:
- Delegation framework
- Advanced Permissions (ERC-7715)
- User operation batching
- Gas abstraction support
**Benefits**:
- Enhanced security
- Better user experience
- Lower transaction costs
- Developer-friendly SDK
**Availability**:
Smart Accounts are now available on ChainID 138. Users can create Smart Accounts and developers can integrate using the comprehensive SDK and documentation.
**Resources**:
- Documentation: [link]
- Developer Guide: [link]
- Examples: [link]
---
## Documentation Links
### For Users
- [User Guide](./SMART_ACCOUNTS_USER_GUIDE.md)
- [FAQ](./SMART_ACCOUNTS_FAQ.md)
- [Troubleshooting](./SMART_ACCOUNTS_TROUBLESHOOTING.md)
### For Developers
- [Developer Guide](./SMART_ACCOUNTS_DEVELOPER_GUIDE.md)
- [API Reference](./SMART_ACCOUNTS_API_REFERENCE.md)
- [Integration Examples](../examples/)
---
## Community Channels
### Recommended Channels
- **Discord**: Create Smart Accounts channel
- **GitHub**: Discussions for questions
- **Twitter**: Announcements and updates
- **Documentation**: Comprehensive guides
---
## Metrics to Highlight
### User Metrics
- Account creation time: < 5 seconds
- Delegation approval: < 10 seconds
- Gas savings: > 30% (with batching)
### Developer Metrics
- Easy integration
- Complete SDK
- Comprehensive documentation
- Active support
---
**Last Updated**: 2026-01-26

229
docs/PERFORMANCE_TESTING_GUIDE.md Normal file
View File

@@ -0,0 +1,229 @@
# Performance Testing Guide - Smart Accounts
**Date**: 2026-01-26
**Network**: ChainID 138 (SMOM-DBIS-138)
---
## Overview
This guide explains how to perform performance testing for Smart Accounts Kit integration.
---
## Performance Metrics
### Key Metrics
1. **Smart Account Creation Time**
- Target: < 5 seconds
- Measurement: Time from request to account creation
2. **Delegation Request Time**
- Target: < 10 seconds
- Measurement: Time from request to approval
3. **User Operation Batch Time**
- Target: < 15 seconds
- Measurement: Time from batch creation to execution
4. **Gas Usage**
- Target: Optimize for batch operations
- Measurement: Gas per operation
---
## Testing Tools
### 1. Performance Test Script
**File**: `scripts/performance-test.sh`
**Usage**:
```bash
./scripts/performance-test.sh
```
**Tests**:
- Smart account creation performance
- Delegation performance
- Batch operations performance
### 2. Load Testing
**Tools**:
- Apache Bench (ab)
- wrk
- k6
- Artillery
**Example**:
```bash
# Load test smart account creation
ab -n 100 -c 10 https://api.d-bis.org/smart-accounts/create
```
### 3. Gas Benchmarking
**Tool**: Foundry gas reporting
**Usage**:
```bash
forge test --match-path test/smart-accounts/** --gas-report
```
---
## Test Scenarios
### Scenario 1: Smart Account Creation
**Test**: Create 100 smart accounts sequentially
**Metrics**:
- Total time
- Average time per account
- Peak time
- Success rate
**Expected Results**:
- Average: < 5 seconds
- Peak: < 10 seconds
- Success rate: > 99%
### Scenario 2: Delegation Requests
**Test**: Request 50 delegations
**Metrics**:
- Total time
- Average time per delegation
- Success rate
**Expected Results**:
- Average: < 10 seconds
- Success rate: > 95%
### Scenario 3: Batch Operations
**Test**: Execute 100 batch operations
**Metrics**:
- Total time
- Average time per batch
- Gas savings vs individual operations
**Expected Results**:
- Average: < 15 seconds
- Gas savings: > 30%
---
## Performance Optimization
### 1. Gas Optimization
- Use batch operations
- Optimize storage patterns
- Minimize external calls
- Use events instead of storage where possible
### 2. Network Optimization
- Use efficient RPC endpoints
- Implement connection pooling
- Cache frequently accessed data
- Use batch RPC calls
### 3. Caching
- Cache smart account addresses
- Cache delegation status
- Cache permission status
- Invalidate on updates
---
## Monitoring Performance
### Real-time Metrics
```typescript
// Track account creation time
const startTime = Date.now();
const account = await kit.createAccount({ owner: userAddress });
const duration = Date.now() - startTime;
// Log to analytics
analytics.track('account_created', {
duration,
gasUsed: receipt.gasUsed,
});
```
### Performance Dashboard
Configure Grafana dashboard with:
- Account creation rate
- Average creation time
- Delegation success rate
- Gas usage trends
- Error rates
---
## Benchmarking
### Baseline Metrics
Before optimization:
- Account creation: ~10 seconds
- Delegation: ~15 seconds
- Batch operations: ~20 seconds
### Target Metrics
After optimization:
- Account creation: < 5 seconds
- Delegation: < 10 seconds
- Batch operations: < 15 seconds
---
## Troubleshooting Performance Issues
### Issue: Slow Account Creation
**Causes**:
- Network latency
- RPC endpoint issues
- Gas price too low
**Solutions**:
- Use faster RPC endpoint
- Increase gas price
- Implement retry logic
### Issue: High Gas Usage
**Causes**:
- Inefficient contract code
- Too many operations
- No batching
**Solutions**:
- Optimize contract code
- Use batch operations
- Cache results
---
## Resources
- [Performance Testing Script](./scripts/performance-test.sh)
- [Monitoring Configuration](./config/monitoring-config.json)
- [Analytics Configuration](./config/analytics-config.json)
---
**Last Updated**: 2026-01-26

185
docs/QUICK_START_DEPLOYMENT.md Normal file
View File

@@ -0,0 +1,185 @@
# Quick Start Deployment Guide - Smart Accounts
**Date**: 2026-01-26
**Network**: ChainID 138 (SMOM-DBIS-138)
---
## Overview
This guide provides a quick start for deploying Smart Accounts Kit on ChainID 138.
---
## Prerequisites
### Required
- **Foundry**: Installed and configured
- **Node.js**: v18 or higher
- **RPC Access**: Access to ChainID 138 RPC endpoint
- **ETH Balance**: Sufficient ETH for gas fees
### Environment Setup
1. **Set up environment variables** in `smom-dbis-138/.env`:
```bash
RPC_URL_138=https://rpc.d-bis.org
PRIVATE_KEY=your_private_key_here
```
2. **Verify prerequisites**:
```bash
forge --version
node --version
```
---
## Quick Deployment (5 Steps)
### Step 1: Install SDK
```bash
cd metamask-integration
./scripts/install-smart-accounts-sdk.sh
```
### Step 2: Deploy Smart Accounts Kit Contracts
```bash
cd ../smom-dbis-138
forge script script/smart-accounts/DeploySmartAccountsKit.s.sol \
--rpc-url $RPC_URL_138 \
--broadcast \
--verify
```
**Record the deployed addresses**:
- EntryPoint address
- AccountFactory address
- Paymaster address (if deployed)
### Step 3: Update Configuration
```bash
cd ../metamask-integration
./scripts/update-smart-accounts-config.sh --interactive
```
Enter the deployed contract addresses when prompted.
### Step 4: Deploy AccountWalletRegistryExtended
```bash
cd ../smom-dbis-138
# Set environment variables first
export SMART_ACCOUNT_FACTORY=<AccountFactory address>
export ENTRY_POINT=<EntryPoint address>
forge script script/smart-accounts/DeployAccountWalletRegistryExtended.s.sol \
--rpc-url $RPC_URL_138 \
--broadcast \
--verify
```
### Step 5: Verify Deployment
```bash
cd ../metamask-integration
./scripts/verify-deployment.sh
./scripts/health-check.sh
```
---
## Automated Deployment
For a fully automated deployment:
```bash
cd metamask-integration
./scripts/deploy-smart-accounts-complete.sh
```
**Note**: You'll still need to manually update configuration with contract addresses after deployment.
---
## Post-Deployment
### 1. Setup Monitoring
```bash
./scripts/setup-monitoring.sh
```
### 2. Run Tests
```bash
# Unit tests
cd ../smom-dbis-138
forge test --match-path test/smart-accounts/** -vv
# Integration tests
cd ../metamask-integration
npm test
```
### 3. Validate Configuration
```bash
./scripts/validate-config.sh
```
---
## Verification Checklist
- [ ] SDK installed
- [ ] Contracts deployed
- [ ] Configuration updated
- [ ] AccountWalletRegistryExtended deployed
- [ ] Health check passed
- [ ] Tests passing
- [ ] Monitoring configured
---
## Troubleshooting
### Common Issues
**Issue**: RPC connection failed
- **Solution**: Verify `RPC_URL_138` is correct and accessible
**Issue**: Insufficient gas
- **Solution**: Ensure deployer address has sufficient ETH
**Issue**: Contract verification failed
- **Solution**: Check block explorer API key and network connectivity
**Issue**: Configuration validation failed
- **Solution**: Run `./scripts/validate-config.sh` to identify issues
---
## Next Steps
1. **Security Audit**: Review [Security Audit Preparation](./SECURITY_AUDIT_PREPARATION.md)
2. **Testing**: Follow [Testing Guide](./TESTING_GUIDE.md)
3. **Monitoring**: Setup monitoring per [Infrastructure Setup](./INFRASTRUCTURE_SETUP.md)
4. **Documentation**: Review all guides in `docs/` directory
---
## Resources
- [Deployment Checklist](../DEPLOYMENT_CHECKLIST.md)
- [Developer Guide](./SMART_ACCOUNTS_DEVELOPER_GUIDE.md)
- [Troubleshooting Guide](./SMART_ACCOUNTS_TROUBLESHOOTING.md)
- [API Reference](./SMART_ACCOUNTS_API_REFERENCE.md)
---
**Last Updated**: 2026-01-26

171
docs/ROLLBACK_PROCEDURES.md Normal file
View File

@@ -0,0 +1,171 @@
# Rollback Procedures - Smart Accounts
**Date**: 2026-01-26
**Network**: ChainID 138 (SMOM-DBIS-138)
---
## Overview
This guide explains rollback procedures for Smart Accounts deployments and upgrades.
---
## Rollback Scenarios
### Scenario 1: Contract Deployment Issues
**Symptoms**:
- Contracts deployed incorrectly
- Functionality not working
- Security concerns
**Rollback**:
1. **Pause New Contracts**: Pause affected contracts if possible
2. **Revert to Previous**: Use previous contract versions
3. **Update Configuration**: Update config to point to previous contracts
4. **Verify**: Test that rollback works
5. **Investigate**: Identify and fix issues
---
### Scenario 2: Configuration Issues
**Symptoms**:
- Configuration errors
- Wrong addresses
- Incorrect settings
**Rollback**:
1. **Restore Backup**: Restore previous configuration
```bash
./backups/recover-smart-accounts-config.sh <timestamp>
```
2. **Restart Services**: Restart affected services
3. **Verify**: Test functionality
4. **Fix**: Correct configuration issues
---
### Scenario 3: SDK Upgrade Issues
**Symptoms**:
- SDK version incompatible
- Breaking changes
- Functionality broken
**Rollback**:
1. **Downgrade SDK**: Install previous version
```bash
npm install @metamask/smart-accounts-kit@<previous-version>
```
2. **Update Code**: Revert code changes if needed
3. **Test**: Verify functionality
4. **Fix**: Address compatibility issues
---
## Rollback Checklist
### Pre-Rollback
- [ ] Identify issue
- [ ] Assess impact
- [ ] Locate backup/previous version
- [ ] Prepare rollback plan
- [ ] Notify team
### Rollback
- [ ] Pause affected systems
- [ ] Restore previous version
- [ ] Update configuration
- [ ] Restart services
- [ ] Verify functionality
### Post-Rollback
- [ ] Monitor for issues
- [ ] Verify all features work
- [ ] Document rollback
- [ ] Investigate root cause
- [ ] Plan fix
---
## Backup Locations
### Configuration Backups
**Location**: `backups/`
**Files**:
- `smart-accounts-config_<timestamp>.json`
- `monitoring-config_<timestamp>.json`
**Restore**:
```bash
./backups/recover-smart-accounts-config.sh <timestamp>
```
### Contract Backups
**Location**: Block explorer (immutable)
**Information**:
- Previous contract addresses
- Previous deployment transactions
- Previous contract code
---
## Emergency Procedures
### Critical Issues
**Immediate Actions**:
1. **Pause Contracts**: Pause if pause function available
2. **Disable Features**: Disable affected features
3. **Notify Users**: Communicate issue
4. **Investigate**: Identify root cause
5. **Fix**: Implement fix
6. **Test**: Test fix thoroughly
7. **Deploy**: Deploy fix
### Communication
- Notify stakeholders immediately
- Provide status updates
- Document all actions
- Post-mortem after resolution
---
## Prevention
### Best Practices
1. **Test Thoroughly**: Test before deployment
2. **Staged Rollout**: Deploy gradually
3. **Monitor Closely**: Watch for issues
4. **Keep Backups**: Regular backups
5. **Document Changes**: Document all changes
### Testing
- Test on testnet first
- Test with small user group
- Monitor metrics
- Watch for errors
---
## Resources
- [Deployment Checklist](./DEPLOYMENT_CHECKLIST.md)
- [Troubleshooting Guide](./SMART_ACCOUNTS_TROUBLESHOOTING.md)
- [Incident Response](./INCIDENT_RESPONSE.md)
---
**Last Updated**: 2026-01-26

426
docs/SDK_API_REFERENCE.md Normal file
View File

@@ -0,0 +1,426 @@
# MetaMask SDK API Reference
Complete API reference for the MetaMask SDK for ChainID 138.
## Installation
```bash
npm install @defi-oracle/metamask-sdk
# or
cd smom-dbis-138/metamask-sdk
npm install
```
## Import
```typescript
import {
addNetwork,
switchNetwork,
addOrSwitchNetwork,
isNetworkAdded,
isOnChain138,
getCurrentChainId,
addToken,
addTokenFromList,
CHAIN_ID,
CHAIN_ID_HEX,
CHAIN_NAME,
RPC_URLS,
BLOCK_EXPLORER_URL,
NETWORK_METADATA,
} from '@defi-oracle/metamask-sdk';
```
---
## Network Functions
### `addNetwork(customMetadata?)`
Adds ChainID 138 to MetaMask.
**Parameters**:
- `customMetadata?` (optional): Custom network metadata to override defaults
**Returns**: `Promise<void>`
**Throws**:
- `Error` if MetaMask is not installed
- `Error` if user rejects the request
- `Error` if network addition fails
**Example**:
```typescript
try {
await addNetwork();
console.log('ChainID 138 added to MetaMask');
} catch (error) {
console.error('Failed to add network:', error);
}
```
---
### `switchNetwork()`
Switches MetaMask to ChainID 138.
**Returns**: `Promise<void>`
**Throws**:
- `Error` if MetaMask is not installed
- `Error` if ChainID 138 is not added (use `addNetwork()` first)
- `Error` if user rejects the request
- `Error` if network switch fails
**Example**:
```typescript
try {
await switchNetwork();
console.log('Switched to ChainID 138');
} catch (error) {
if (error.code === 4902) {
// Chain not added, add it first
await addNetwork();
} else {
console.error('Failed to switch network:', error);
}
}
```
---
### `addOrSwitchNetwork()`
Adds ChainID 138 if not added, or switches to it if already added.
**Returns**: `Promise<void>`
**Throws**:
- `Error` if MetaMask is not installed
- `Error` if user rejects the request
- `Error` if operation fails
**Example**:
```typescript
try {
await addOrSwitchNetwork();
console.log('Connected to ChainID 138');
} catch (error) {
console.error('Failed to connect:', error);
}
```
---
### `isNetworkAdded()`
Checks if ChainID 138 is already added to MetaMask.
**Returns**: `Promise<boolean>`
**Throws**:
- `Error` if MetaMask is not installed
**Example**:
```typescript
const isAdded = await isNetworkAdded();
if (isAdded) {
console.log('ChainID 138 is already added');
} else {
console.log('ChainID 138 is not added');
}
```
---
### `isOnChain138()`
Checks if MetaMask is currently connected to ChainID 138.
**Returns**: `Promise<boolean>`
**Throws**:
- `Error` if MetaMask is not installed
**Example**:
```typescript
const isOn138 = await isOnChain138();
if (isOn138) {
console.log('Currently on ChainID 138');
} else {
console.log('Not on ChainID 138');
}
```
---
### `getCurrentChainId()`
Gets the current chain ID from MetaMask.
**Returns**: `Promise<number>`
**Throws**:
- `Error` if MetaMask is not installed
**Example**:
```typescript
const chainId = await getCurrentChainId();
console.log('Current chain ID:', chainId);
if (chainId === 138) {
console.log('On ChainID 138');
}
```
---
## Token Functions
### `addToken(address, symbol, decimals, image?)`
Adds an ERC-20 token to MetaMask.
**Parameters**:
- `address` (string): Token contract address
- `symbol` (string): Token symbol (e.g., "cUSDT")
- `decimals` (number): Token decimals (e.g., 6 for cUSDT)
- `image?` (optional string): Token logo URL
**Returns**: `Promise<void>`
**Throws**:
- `Error` if MetaMask is not installed
- `Error` if user rejects the request
- `Error` if token addition fails
**Example**:
```typescript
try {
await addToken(
'0x93E66202A11B1772E55407B32B44e5Cd8eda7f22',
'cUSDT',
6,
'https://explorer.d-bis.org/images/tokens/0x93E66202A11B1772E55407B32B44e5Cd8eda7f22.png'
);
console.log('cUSDT added to MetaMask');
} catch (error) {
console.error('Failed to add token:', error);
}
```
---
### `addTokenFromList(token)`
Adds a token from a token list entry.
**Parameters**:
- `token` (object): Token list entry with `address`, `symbol`, `decimals`, `logoURI`
**Returns**: `Promise<void>`
**Example**:
```typescript
const token = {
address: '0x93E66202A11B1772E55407B32B44e5Cd8eda7f22',
symbol: 'cUSDT',
decimals: 6,
logoURI: 'https://explorer.d-bis.org/images/tokens/0x93E66202A11B1772E55407B32B44e5Cd8eda7f22.png'
};
try {
await addTokenFromList(token);
console.log('Token added from list');
} catch (error) {
console.error('Failed to add token:', error);
}
```
---
## Constants
### `CHAIN_ID`
Chain ID number: `138`
### `CHAIN_ID_HEX`
Chain ID in hex: `'0x8a'`
### `CHAIN_NAME`
Chain name: `'DeFi Oracle Meta Mainnet'`
### `RPC_URLS`
Array of RPC endpoint URLs:
```typescript
[
'https://rpc.d-bis.org',
'https://rpc2.d-bis.org'
]
```
### `BLOCK_EXPLORER_URL`
Block explorer URL: `'https://explorer.d-bis.org'`
### `NETWORK_METADATA`
Complete network metadata for `wallet_addEthereumChain`:
```typescript
{
chainId: '0x8a',
chainName: 'DeFi Oracle Meta Mainnet',
nativeCurrency: {
name: 'Ether',
symbol: 'ETH',
decimals: 18,
},
rpcUrls: ['https://rpc.d-bis.org', 'https://rpc2.d-bis.org'],
blockExplorerUrls: ['https://explorer.d-bis.org'],
}
```
---
## Error Handling
All functions can throw errors. Always use try-catch:
```typescript
try {
await addNetwork();
} catch (error: any) {
if (error.message?.includes('MetaMask is not installed')) {
// Handle MetaMask not installed
alert('Please install MetaMask');
} else if (error.code === 4001) {
// User rejected the request
console.log('User rejected network addition');
} else {
// Other errors
console.error('Error:', error);
}
}
```
### Common Error Codes
- `4001`: User rejected the request
- `4902`: Chain not added (for switchNetwork)
- `-32603`: Internal JSON-RPC error
- `-32002`: Request already pending
---
## Complete Examples
### React Hook Example
```typescript
import { useState, useEffect } from 'react';
import { addOrSwitchNetwork, isOnChain138, addToken } from '@defi-oracle/metamask-sdk';
function useChain138() {
const [isConnected, setIsConnected] = useState(false);
const [isLoading, setIsLoading] = useState(false);
const [error, setError] = useState<string | null>(null);
const connect = async () => {
setIsLoading(true);
setError(null);
try {
await addOrSwitchNetwork();
const isOn138 = await isOnChain138();
setIsConnected(isOn138);
} catch (err: any) {
setError(err.message);
setIsConnected(false);
} finally {
setIsLoading(false);
}
};
return { isConnected, isLoading, error, connect };
}
```
### Vue Composable Example
```typescript
import { ref } from 'vue';
import { addOrSwitchNetwork, isOnChain138, addToken } from '@defi-oracle/metamask-sdk';
export function useChain138() {
const isConnected = ref(false);
const isLoading = ref(false);
const error = ref<string | null>(null);
const connect = async () => {
isLoading.value = true;
error.value = null;
try {
await addOrSwitchNetwork();
const isOn138 = await isOnChain138();
isConnected.value = isOn138;
} catch (err: any) {
error.value = err.message;
isConnected.value = false;
} finally {
isLoading.value = false;
}
};
return { isConnected, isLoading, error, connect };
}
```
---
## TypeScript Types
```typescript
// Network metadata type
interface NetworkMetadata {
chainId: string;
chainName: string;
nativeCurrency: {
name: string;
symbol: string;
decimals: number;
};
rpcUrls: string[];
blockExplorerUrls: string[];
iconUrls?: string[];
}
// Token metadata type
interface TokenMetadata {
address: string;
symbol: string;
decimals: number;
image?: string;
}
```
---
## Browser Compatibility
- ✅ Chrome/Chromium (MetaMask Extension)
- ✅ Firefox (MetaMask Extension)
- ✅ Edge (MetaMask Extension)
- ✅ Brave (MetaMask Extension)
- ✅ MetaMask Mobile (in-app browser)
---
## Requirements
- MetaMask extension or mobile app installed
- MetaMask unlocked
- User approval for network/token operations
---
**Last Updated**: 2026-01-26

267
docs/SECURITY_AUDIT_PREPARATION.md Normal file
View File

@@ -0,0 +1,267 @@
# Security Audit Preparation - Smart Accounts
**Date**: 2026-01-26
**Network**: ChainID 138 (SMOM-DBIS-138)
---
## Overview
This document outlines the security audit preparation for Smart Accounts Kit integration contracts.
---
## Contracts to Audit
### 1. AccountWalletRegistryExtended
**File**: `contracts/smart-accounts/AccountWalletRegistryExtended.sol`
**Key Functions**:
- `linkSmartAccount()` - Links smart account to fiat account
- `isSmartAccount()` - Checks if wallet is smart account
- `setSmartAccountFactory()` - Updates factory address
- `setEntryPoint()` - Updates EntryPoint address
**Security Concerns**:
- Access control (role-based)
- Input validation
- Smart account verification
- Reentrancy protection
---
### 2. Smart Accounts Kit Contracts (External)
**Contracts**:
- EntryPoint (ERC-4337)
- AccountFactory
- Paymaster (optional)
**Note**: These are external contracts from MetaMask Smart Accounts Kit. Review their security audits.
---
## Audit Checklist
### Access Control
- [ ] Role-based access control implemented correctly
- [ ] Admin functions protected
- [ ] Role assignment verified
- [ ] Role revocation works correctly
### Input Validation
- [ ] Zero address checks
- [ ] Parameter validation
- [ ] Array bounds checking
- [ ] Type validation
### Smart Account Verification
- [ ] Contract detection works correctly
- [ ] Smart account validation
- [ ] Address format validation
- [ ] Duplicate prevention
### Reentrancy Protection
- [ ] Reentrancy guards in place
- [ ] State changes before external calls
- [ ] Checks-Effects-Interactions pattern
### Gas Optimization
- [ ] Gas-efficient storage patterns
- [ ] Loop optimization
- [ ] Unnecessary operations removed
### Event Emission
- [ ] All state changes emit events
- [ ] Event parameters complete
- [ ] Indexed parameters for filtering
---
## Known Security Considerations
### 1. Smart Account Verification
**Risk**: EOA could be mistaken for smart account
**Mitigation**:
- Check `extcodesize` > 0
- Verify contract has code
### 2. Factory Address Updates
**Risk**: Malicious factory address
**Mitigation**:
- Admin-only function
- Verify factory address before update
- Consider timelock for critical updates
### 3. EntryPoint Address Updates
**Risk**: Malicious EntryPoint address
**Mitigation**:
- Admin-only function
- Verify EntryPoint address
- Consider timelock for critical updates
---
## Testing Requirements
### Unit Tests
- [ ] Access control tests
- [ ] Input validation tests
- [ ] Smart account detection tests
- [ ] Edge case tests
### Integration Tests
- [ ] End-to-end flow tests
- [ ] Multi-contract interaction tests
- [ ] Failure mode tests
### Fuzz Tests
- [ ] Fuzz input parameters
- [ ] Fuzz state transitions
- [ ] Fuzz edge cases
### Invariant Tests
- [ ] State invariants
- [ ] Access control invariants
- [ ] Data consistency invariants
---
## Audit Deliverables
### 1. Code Documentation
- [ ] NatSpec comments on all functions
- [ ] Architecture documentation
- [ ] Security considerations documented
### 2. Test Coverage
- [ ] Unit test coverage > 90%
- [ ] Integration test coverage > 80%
- [ ] Fuzz test coverage
- [ ] Invariant test coverage
### 3. Security Documentation
- [ ] Threat model
- [ ] Security assumptions
- [ ] Known limitations
- [ ] Risk assessment
---
## Recommended Audit Firms
### Smart Contract Auditors
1. **Trail of Bits**
- Experience with account abstraction
- ERC-4337 expertise
2. **OpenZeppelin**
- Smart account experience
- Access control expertise
3. **Consensys Diligence**
- MetaMask integration experience
- Security best practices
4. **CertiK**
- Comprehensive audits
- Formal verification
---
## Audit Scope
### In Scope
- AccountWalletRegistryExtended contract
- Integration with existing AccountWalletRegistry
- Smart account linking logic
- Access control implementation
### Out of Scope
- MetaMask Smart Accounts Kit contracts (external)
- EntryPoint contract (external, already audited)
- AccountFactory contract (external, already audited)
- Paymaster contract (external, optional)
---
## Pre-Audit Checklist
### Code Quality
- [ ] Code formatted (forge fmt)
- [ ] No compiler warnings
- [ ] All tests passing
- [ ] Documentation complete
### Security
- [ ] Slither analysis run
- [ ] Mythril analysis run
- [ ] Manual security review
- [ ] Known issues documented
### Testing
- [ ] Unit tests complete
- [ ] Integration tests complete
- [ ] Fuzz tests complete
- [ ] Coverage > 90%
---
## Post-Audit Actions
### 1. Address Findings
- [ ] Review audit report
- [ ] Prioritize findings
- [ ] Fix critical issues
- [ ] Fix high-priority issues
- [ ] Document medium/low issues
### 2. Re-testing
- [ ] Re-run all tests
- [ ] Verify fixes
- [ ] Update documentation
### 3. Re-audit (if needed)
- [ ] Schedule re-audit for critical fixes
- [ ] Verify all issues resolved
---
## Resources
- [OpenZeppelin Security Best Practices](https://docs.openzeppelin.com/contracts/security)
- [Consensys Best Practices](https://consensys.github.io/smart-contract-best-practices/)
- [Trail of Bits Security Guide](https://github.com/crytic/building-secure-contracts)
---
**Last Updated**: 2026-01-26

354
docs/SMART_ACCOUNTS_API_REFERENCE.md Normal file
View File

@@ -0,0 +1,354 @@
# Smart Accounts API Reference
**Date**: 2026-01-26
**Network**: ChainID 138 (SMOM-DBIS-138)
---
## Overview
Complete API reference for Smart Accounts Kit integration.
---
## SmartAccountsKit Class
### Constructor
```typescript
new SmartAccountsKit(options: SmartAccountsKitOptions)
```
**Options**:
```typescript
interface SmartAccountsKitOptions {
chainId: number;
rpcUrl: string;
entryPointAddress: string;
accountFactoryAddress: string;
paymasterAddress?: string;
}
```
**Example**:
```typescript
const kit = new SmartAccountsKit({
chainId: 138,
rpcUrl: 'https://rpc.d-bis.org',
entryPointAddress: '0x...',
accountFactoryAddress: '0x...',
});
```
---
## Methods
### createAccount()
Creates a new Smart Account.
```typescript
createAccount(options: CreateAccountOptions): Promise<SmartAccount>
```
**Options**:
```typescript
interface CreateAccountOptions {
owner: string;
salt?: string;
}
```
**Returns**: `Promise<SmartAccount>`
**Example**:
```typescript
const account = await kit.createAccount({
owner: userAddress,
});
```
---
### requestDelegation()
Requests delegation from user.
```typescript
requestDelegation(options: DelegationOptions): Promise<DelegationResult>
```
**Options**:
```typescript
interface DelegationOptions {
target: string;
permissions: string[];
expiry: number;
rules?: DelegationRules;
}
```
**Returns**: `Promise<DelegationResult>`
**Example**:
```typescript
const delegation = await kit.requestDelegation({
target: dAppAddress,
permissions: ['execute_transactions'],
expiry: Date.now() + 86400000,
});
```
---
### getDelegationStatus()
Gets delegation status.
```typescript
getDelegationStatus(options: DelegationStatusOptions): Promise<DelegationStatus>
```
**Options**:
```typescript
interface DelegationStatusOptions {
target: string;
account: string;
}
```
**Returns**: `Promise<DelegationStatus>`
**Example**:
```typescript
const status = await kit.getDelegationStatus({
target: dAppAddress,
account: smartAccountAddress,
});
```
---
### revokeDelegation()
Revokes delegation.
```typescript
revokeDelegation(options: RevokeDelegationOptions): Promise<void>
```
**Options**:
```typescript
interface RevokeDelegationOptions {
target: string;
account: string;
}
```
**Example**:
```typescript
await kit.revokeDelegation({
target: dAppAddress,
account: smartAccountAddress,
});
```
---
### requestAdvancedPermission()
Requests Advanced Permission (ERC-7715).
```typescript
requestAdvancedPermission(options: PermissionOptions): Promise<PermissionResult>
```
**Options**:
```typescript
interface PermissionOptions {
target: string;
functionSelector: string;
allowed: boolean;
conditions?: PermissionConditions;
}
```
**Returns**: `Promise<PermissionResult>`
**Example**:
```typescript
const permission = await kit.requestAdvancedPermission({
target: contractAddress,
functionSelector: '0xa9059cbb',
allowed: true,
});
```
---
### hasPermission()
Checks if permission is granted.
```typescript
hasPermission(options: CheckPermissionOptions): Promise<boolean>
```
**Options**:
```typescript
interface CheckPermissionOptions {
account: string;
target: string;
functionSelector: string;
}
```
**Returns**: `Promise<boolean>`
**Example**:
```typescript
const hasPermission = await kit.hasPermission({
account: smartAccountAddress,
target: contractAddress,
functionSelector: '0xa9059cbb',
});
```
---
### batchUserOperations()
Creates batch of user operations.
```typescript
batchUserOperations(operations: UserOperation[]): Promise<UserOperation[]>
```
**Operations**:
```typescript
interface UserOperation {
to: string;
data: string;
value: string;
}
```
**Returns**: `Promise<UserOperation[]>`
**Example**:
```typescript
const userOps = await kit.batchUserOperations([
{
to: tokenAddress,
data: transferData,
value: '0',
},
]);
```
---
### executeBatch()
Executes batch of user operations.
```typescript
executeBatch(userOps: UserOperation[]): Promise<TransactionResult>
```
**Returns**: `Promise<TransactionResult>`
**Example**:
```typescript
const result = await kit.executeBatch(userOps);
console.log('Transaction hash:', result.hash);
```
---
## AccountWalletRegistryExtended Contract
### linkSmartAccount()
Links Smart Account to fiat account.
```solidity
function linkSmartAccount(
bytes32 accountRefId,
address smartAccount,
bytes32 provider
) external onlyRole(ACCOUNT_MANAGER_ROLE)
```
**Parameters**:
- `accountRefId`: Hashed account reference ID
- `smartAccount`: Smart Account address
- `provider`: Provider identifier (e.g., "METAMASK_SMART_ACCOUNT")
**Events**:
- `SmartAccountLinked(accountRefId, smartAccount, provider)`
---
### isSmartAccount()
Checks if wallet is Smart Account.
```solidity
function isSmartAccount(bytes32 walletRefId) external view returns (bool)
```
**Parameters**:
- `walletRefId`: Hashed wallet reference ID
**Returns**: `bool`
---
### isSmartAccountAddress()
Checks if address is Smart Account.
```solidity
function isSmartAccountAddress(address accountAddress) external view returns (bool)
```
**Parameters**:
- `accountAddress`: Account address to check
**Returns**: `bool`
---
## Error Handling
### Common Errors
**USER_REJECTED**:
- User rejected transaction
- Handle gracefully
**INSUFFICIENT_FUNDS**:
- Insufficient ETH for gas
- Prompt user to add funds
**PERMISSION_DENIED**:
- Permission not granted
- Request permission first
**DELEGATION_EXPIRED**:
- Delegation has expired
- Request new delegation
---
## Resources
- [Developer Guide](./SMART_ACCOUNTS_DEVELOPER_GUIDE.md)
- [Delegation Guide](./DELEGATION_USAGE_GUIDE.md)
- [Permissions Guide](./ADVANCED_PERMISSIONS_GUIDE.md)
---
**Last Updated**: 2026-01-26

111
docs/SMART_ACCOUNTS_DEPLOYMENT_NOTE.md Normal file
View File

@@ -0,0 +1,111 @@
# Smart Accounts Kit Deployment - Important Note
**Date**: 2026-01-26
**Status**: ⚠️ **Contract Sources Required**
---
## Important Deployment Note
MetaMask Smart Accounts Kit uses **ERC-4337 standard contracts** that need to be deployed:
1. **EntryPoint Contract** (ERC-4337 standard)
2. **AccountFactory Contract** (MetaMask Smart Accounts Kit)
3. **Paymaster Contract** (Optional, for gas abstraction)
---
## Contract Sources
### Option 1: MetaMask Smart Accounts Kit Package
The contracts may be available in the `@metamask/smart-accounts-kit` package:
```bash
npm install @metamask/smart-accounts-kit
# Check for contract artifacts in node_modules/@metamask/smart-accounts-kit
```
### Option 2: Standard ERC-4337 Implementations
Use standard ERC-4337 implementations:
- **OpenZeppelin**: ERC-4337 contracts
- **Alchemy**: Account Abstraction SDK
- **Stackup**: ERC-4337 implementations
- **Pimlico**: ERC-4337 contracts
### Option 3: Use Existing Deployments
If EntryPoint and AccountFactory are already deployed on ChainID 138, use those addresses.
---
## Deployment Steps
### Step 1: Obtain Contract Sources
1. Check `@metamask/smart-accounts-kit` package for contracts
2. Or use standard ERC-4337 implementations
3. Or verify if contracts are already deployed
### Step 2: Deploy Contracts
Once contract sources are available:
```bash
# Deploy EntryPoint
forge script script/smart-accounts/DeployEntryPoint.s.sol \
--rpc-url $RPC_URL_138 --broadcast
# Deploy AccountFactory
forge script script/smart-accounts/DeployAccountFactory.s.sol \
--rpc-url $RPC_URL_138 --broadcast
# Deploy Paymaster (optional)
forge script script/smart-accounts/DeployPaymaster.s.sol \
--rpc-url $RPC_URL_138 --broadcast
```
### Step 3: Update Configuration
```bash
# Update .env
echo "ENTRY_POINT=<deployed-address>" >> smom-dbis-138/.env
echo "SMART_ACCOUNT_FACTORY=<deployed-address>" >> smom-dbis-138/.env
echo "PAYMASTER=<deployed-address>" >> smom-dbis-138/.env # optional
# Update config
cd metamask-integration
./scripts/update-smart-accounts-config.sh --interactive
```
### Step 4: Deploy AccountWalletRegistryExtended
```bash
cd smom-dbis-138
forge script script/smart-accounts/DeployAccountWalletRegistryExtended.s.sol \
--rpc-url $RPC_URL_138 --broadcast
```
---
## Current Status
✅ **Deployment script created**: `script/smart-accounts/DeploySmartAccountsKit.s.sol`
⚠️ **Contract sources needed**: EntryPoint and AccountFactory implementations
✅ **AccountWalletRegistryExtended ready**: Can be deployed once factory/entry point addresses are set
---
## Next Steps
1. **Obtain contract sources** from MetaMask Smart Accounts Kit or ERC-4337 implementations
2. **Create deployment scripts** for EntryPoint and AccountFactory
3. **Deploy contracts** to ChainID 138
4. **Update configuration** with deployed addresses
5. **Deploy AccountWalletRegistryExtended**
---
**Last Updated**: 2026-01-26

280
docs/SMART_ACCOUNTS_FAQ.md Normal file
View File

@@ -0,0 +1,280 @@
# Smart Accounts FAQ
**Date**: 2026-01-26
**Network**: ChainID 138 (SMOM-DBIS-138)
---
## General Questions
### Q: What are Smart Accounts?
**A**: Smart Accounts are programmable accounts that enable:
- Delegation (share permissions with dApps)
- Advanced Permissions (fine-grained access control)
- Batch Operations (multiple transactions in one)
- Gas Abstraction (pay gas in tokens)
---
### Q: What's the difference between EOA and Smart Account?
**A**:
- **EOA** (Externally Owned Account): Standard wallet, no programmable features
- **Smart Account**: Programmable account with delegation and permissions
---
### Q: Can I have both EOA and Smart Account?
**A**: Yes! You can link both to the same fiat account via AccountWalletRegistry.
---
### Q: Are Smart Accounts more secure?
**A**: Smart Accounts offer additional security features:
- Delegation with expiry
- Fine-grained permissions
- Programmable compliance checks
- Multi-signature support
---
### Q: Do I pay more gas with Smart Accounts?
**A**:
- Initial creation costs more
- Batch operations can save gas overall
- Gas abstraction can eliminate gas costs
---
## Delegation Questions
### Q: What is Delegation?
**A**: Delegation allows dApps to execute transactions on your behalf with time-limited permissions.
---
### Q: Can I revoke delegation?
**A**: Yes, you can revoke delegation anytime through MetaMask.
---
### Q: What happens when delegation expires?
**A**: Delegation becomes inactive and cannot be used. You must grant a new delegation.
---
### Q: Can I extend delegation expiry?
**A**: No, you must revoke and re-grant with new expiry.
---
### Q: Can I have multiple delegations?
**A**: Yes, you can grant multiple delegations to different dApps.
---
## Advanced Permissions Questions
### Q: What are Advanced Permissions?
**A**: Advanced Permissions (ERC-7715) are fine-grained, function-level permissions for Smart Accounts.
---
### Q: What's the difference between Delegation and Advanced Permissions?
**A**:
- **Delegation**: Broad permission for dApp to execute transactions
- **Advanced Permissions**: Fine-grained, function-level permissions
---
### Q: Do permissions expire?
**A**: Permissions don't expire automatically, but can be revoked anytime.
---
### Q: Can I grant permission for multiple functions?
**A**: Yes, request permission for each function separately.
---
### Q: Can I have multiple permissions?
**A**: Yes, you can grant multiple permissions for different functions.
---
## Payment Rails Questions
### Q: Can I use Smart Accounts for payment rails?
**A**: Yes, if your Smart Account is linked to a fiat account via AccountWalletRegistry.
---
### Q: How do payment rails work with Smart Accounts?
**A**:
1. Smart Account locks tokens in escrow
2. Settlement orchestrator processes
3. Tokens released after completion
---
### Q: What are the benefits?
**A**:
- Enhanced security
- Delegation with expiry
- Programmable compliance checks
---
## Technical Questions
### Q: How do I create a Smart Account?
**A**:
```typescript
const smartAccount = await kit.createAccount({
owner: userAddress,
});
```
---
### Q: How do I link Smart Account to fiat account?
**A**: Contact your account manager to link your Smart Account address.
---
### Q: How do I check if an address is a Smart Account?
**A**:
```typescript
const isSmart = await registry.isSmartAccountAddress(address);
```
---
### Q: How do I check delegation status?
**A**:
```typescript
const status = await kit.getDelegationStatus({
target: dAppAddress,
account: smartAccountAddress,
});
```
---
### Q: How do I check permission?
**A**:
```typescript
const hasPermission = await kit.hasPermission({
account: smartAccountAddress,
target: contractAddress,
functionSelector: functionSelector,
});
```
---
## Troubleshooting Questions
### Q: Smart Account creation fails. What should I do?
**A**:
1. Check ETH balance for gas
2. Verify RPC connection
3. Check EntryPoint and AccountFactory are deployed
4. Try again after refresh
---
### Q: Delegation not working. What should I do?
**A**:
1. Check delegation is active
2. Verify expiry hasn't passed
3. Check permissions are correct
4. Try revoking and re-granting
---
### Q: Permission denied. What should I do?
**A**:
1. Check MetaMask is unlocked
2. Review permission request details
3. Ensure sufficient gas
4. Try again after refresh
---
## Security Questions
### Q: Are Smart Accounts safe?
**A**: Yes, Smart Accounts use the same security model as standard accounts with additional programmable features.
---
### Q: Can someone steal my Smart Account?
**A**: No, Smart Accounts are secured by the same private key as standard accounts.
---
### Q: What if I lose my private key?
**A**: You lose access to your Smart Account, same as with standard accounts. Consider using hardware wallets.
---
### Q: Can I recover my Smart Account?
**A**: No, if you lose your private key, you cannot recover your Smart Account.
---
## Support Questions
### Q: Where can I get help?
**A**:
1. Check documentation
2. Review troubleshooting guide
3. Contact support team
4. Visit community forums
---
### Q: How do I report a bug?
**A**: Report bugs through support channels or community forums.
---
### Q: Where can I find examples?
**A**: Check the developer guide for code examples.
---
**Last Updated**: 2026-01-26

353
docs/SMART_ACCOUNTS_INTEGRATION_ROADMAP.md Normal file
View File

@@ -0,0 +1,353 @@
# Smart Accounts Kit Integration Roadmap
**Date**: 2026-01-26
**Reference**: [MetaMask Smart Accounts Kit](https://docs.metamask.io/smart-accounts-kit#partner-integrations)
---
## Overview
This roadmap outlines the integration of MetaMask Smart Accounts Kit with the existing Proxmox Smart Vault System.
---
## Current State Analysis
### Existing System
✅ **RailEscrowVault**: Payment rail escrow system
✅ **AccountWalletRegistry**: Fiat account to wallet mapping
✅ **SettlementOrchestrator**: Payment settlement coordination
✅ **Compliance Integration**: Compliance and policy enforcement
### Missing Features
❌ **Smart Accounts**: No programmable accounts
❌ **Delegation**: No delegation framework
❌ **Advanced Permissions**: No ERC-7715 support
❌ **User Operations**: No batch transaction support
❌ **Gas Abstraction**: No gas abstraction
---
## Integration Phases
### Phase 1: Foundation (Weeks 1-2)
**Goal**: Deploy Smart Accounts Kit infrastructure
**Tasks**:
1. ✅ Review Smart Accounts Kit documentation
2. ✅ Create deployment scripts
3. ✅ Deploy EntryPoint contract
4. ✅ Deploy AccountFactory contract
5. ✅ Deploy Paymaster contract (optional)
6. ✅ Configure for ChainID 138
7. ✅ Test smart account creation
**Deliverables**:
- Smart Accounts contracts deployed
- Deployment scripts ready
- Basic smart account creation working
---
### Phase 2: AccountWalletRegistry Integration (Weeks 3-4)
**Goal**: Integrate Smart Accounts with existing AccountWalletRegistry
**Tasks**:
1. ✅ Extend AccountWalletRegistry interface
2. ✅ Add smart account creation on link
3. ✅ Support both EOA and smart accounts
4. ✅ Update API documentation
5. ✅ Test integration
**Deliverables**:
- AccountWalletRegistry supports smart accounts
- Smart accounts auto-created on link
- Both EOA and smart accounts supported
---
### Phase 3: Delegation Framework (Weeks 5-6)
**Goal**: Implement delegation for payment rails and dApps
**Tasks**:
1. ✅ Implement delegation framework
2. ✅ Create delegation rules
3. ✅ Enable permission sharing
4. ✅ Test delegation flows
5. ✅ Create delegation examples
**Deliverables**:
- Delegation framework implemented
- Delegation rules configured
- Delegation examples created
---
### Phase 4: Advanced Permissions (Weeks 7-8)
**Goal**: Implement ERC-7715 Advanced Permissions
**Tasks**:
1. ✅ Implement ERC-7715 standard
2. ✅ Enable permission requests
3. ✅ Manage permission lifecycle
4. ✅ Test permission flows
5. ✅ Create permission examples
**Deliverables**:
- ERC-7715 implemented
- Permission requests working
- Permission examples created
---
### Phase 5: Production Deployment (Weeks 9-10)
**Goal**: Deploy to production and test
**Tasks**:
1. ✅ Security audit
2. ✅ Production deployment
3. ✅ Integration testing
4. ✅ User acceptance testing
5. ✅ Documentation completion
**Deliverables**:
- Production deployment complete
- All features tested
- Documentation complete
---
## Integration Architecture
```
┌─────────────────────────────────────────────────────────┐
│ AccountWalletRegistry │
│ (Extended to support Smart Accounts) │
└───────────────┬─────────────────────────────────────────┘
│
├──► EOA Wallet
│ └──► RailEscrowVault (Payment Rails)
│
└──► Smart Account
├──► Delegation Framework
├──► Advanced Permissions (ERC-7715)
├──► User Operations (Batch)
└──► Gas Abstraction
```
---
## Use Cases
### Use Case 1: Payment Rails with Smart Accounts
**Scenario**: User wants to use smart account for payment rail operations
**Flow**:
1. Create smart account
2. Link to fiat account via AccountWalletRegistry
3. Delegate payment operations to SettlementOrchestrator
4. Use smart account for escrow operations
**Benefits**:
- Enhanced security
- Delegation with expiry
- Programmable compliance checks
### Use Case 2: dApp Integration with Smart Accounts
**Scenario**: dApp wants to execute transactions on behalf of user
**Flow**:
1. User creates smart account
2. dApp requests Advanced Permissions (ERC-7715)
3. User approves permissions
4. dApp executes transactions on behalf of user
**Benefits**:
- Better UX
- Gas abstraction
- Batch operations
### Use Case 3: Hybrid Approach
**Scenario**: User has both EOA and smart account
**Flow**:
1. Link EOA to fiat account (for payment rails)
2. Link smart account to same fiat account
3. Use EOA for payment rails
4. Use smart account for dApp interactions
**Benefits**:
- Flexibility
- Best of both worlds
- Backward compatible
---
## Technical Implementation
### 1. Smart Account Creation
```typescript
import { SmartAccountsKit } from '@metamask/smart-accounts-kit';
const kit = new SmartAccountsKit({
chainId: 138,
rpcUrl: 'https://rpc.d-bis.org',
entryPointAddress: '0x...',
accountFactoryAddress: '0x...',
});
const smartAccount = await kit.createAccount({
owner: userAddress,
});
```
### 2. AccountWalletRegistry Extension
```solidity
// Add to AccountWalletRegistry.sol
function linkSmartAccount(
bytes32 accountRefId,
address smartAccount,
bytes32 provider
) external onlyRole(ACCOUNT_MANAGER_ROLE) {
bytes32 walletRefId = keccak256(abi.encodePacked(smartAccount));
linkAccountToWallet(accountRefId, walletRefId, provider);
}
```
### 3. Delegation for Payment Rails
```typescript
const delegation = await kit.requestDelegation({
target: settlementOrchestratorAddress,
permissions: ['lock_escrow', 'release_escrow'],
expiry: Date.now() + 86400000,
});
```
---
## Testing Plan
### Unit Tests
- [ ] Smart account creation
- [ ] AccountWalletRegistry linking
- [ ] Delegation framework
- [ ] Advanced Permissions
- [ ] User operations batching
### Integration Tests
- [ ] Smart account + RailEscrowVault
- [ ] Smart account + SettlementOrchestrator
- [ ] Delegation + Payment rails
- [ ] Advanced Permissions + dApps
### End-to-End Tests
- [ ] Complete payment rail flow with smart account
- [ ] Complete dApp interaction flow
- [ ] Hybrid EOA + smart account flow
---
## Success Metrics
### Technical Metrics
- ✅ Smart account creation time < 5 seconds
- ✅ Delegation approval time < 10 seconds
- ✅ User operation batch success rate > 99%
- ✅ Gas savings > 30% (via batching)
### User Experience Metrics
- ✅ User satisfaction > 80%
- ✅ Adoption rate > 50% (of eligible users)
- ✅ Error rate < 1%
- ✅ Support tickets < 5% of transactions
---
## Risk Mitigation
### Technical Risks
1. **Smart Account Deployment Issues**
- Mitigation: Thorough testing before production
- Rollback plan: Keep EOA support active
2. **Integration Complexity**
- Mitigation: Phased rollout
- Rollback plan: Feature flags
3. **Gas Costs**
- Mitigation: Paymaster for gas abstraction
- Rollback plan: Optimize contracts
### Business Risks
1. **User Adoption**
- Mitigation: Clear documentation and examples
- Rollback plan: Maintain EOA support
2. **Compliance Issues**
- Mitigation: Review with compliance team
- Rollback plan: Compliance checks in smart accounts
---
## Timeline Summary
| Phase | Duration | Status |
|-------|----------|--------|
| Phase 1: Foundation | 2 weeks | ⏳ Pending |
| Phase 2: AccountWalletRegistry | 2 weeks | ⏳ Pending |
| Phase 3: Delegation | 2 weeks | ⏳ Pending |
| Phase 4: Advanced Permissions | 2 weeks | ⏳ Pending |
| Phase 5: Production | 2 weeks | ⏳ Pending |
| **Total** | **10 weeks** | ⏳ Pending |
---
## Dependencies
### External Dependencies
- ✅ MetaMask Smart Accounts Kit SDK
- ✅ ChainID 138 network support
- ✅ RPC endpoint availability
- ✅ Gas for deployment
### Internal Dependencies
- ✅ AccountWalletRegistry contract
- ✅ RailEscrowVault contract
- ✅ SettlementOrchestrator contract
- ✅ Compliance and policy systems
---
## Next Steps
1. **Review Roadmap**: Get stakeholder approval
2. **Start Phase 1**: Deploy Smart Accounts Kit
3. **Test Integration**: Test with existing systems
4. **Iterate**: Refine based on feedback
5. **Deploy**: Deploy to production
---
**Last Updated**: 2026-01-26

302
docs/SMART_ACCOUNTS_TROUBLESHOOTING.md Normal file
View File

@@ -0,0 +1,302 @@
# Smart Accounts Troubleshooting Guide
**Date**: 2026-01-26
**Network**: ChainID 138 (SMOM-DBIS-138)
---
## Common Issues and Solutions
### Smart Account Creation
#### Issue: Cannot Create Smart Account
**Symptoms**:
- Transaction fails
- Error: "Insufficient funds"
- Error: "Contract deployment failed"
**Solutions**:
1. **Check ETH Balance**: Ensure sufficient ETH for gas
```bash
cast balance $USER_ADDRESS --rpc-url $RPC_URL_138
```
2. **Check RPC Connection**: Verify RPC endpoint is accessible
```bash
cast block-number --rpc-url $RPC_URL_138
```
3. **Check EntryPoint**: Verify EntryPoint is deployed
```bash
cast code $ENTRY_POINT_ADDRESS --rpc-url $RPC_URL_138
```
4. **Check AccountFactory**: Verify AccountFactory is deployed
```bash
cast code $ACCOUNT_FACTORY_ADDRESS --rpc-url $RPC_URL_138
```
---
#### Issue: Smart Account Creation Takes Too Long
**Symptoms**:
- Transaction pending for extended time
- No confirmation received
**Solutions**:
1. **Check Network**: Verify network is not congested
2. **Increase Gas Price**: Use higher gas price
3. **Check Transaction**: Verify transaction was submitted
```bash
cast tx $TX_HASH --rpc-url $RPC_URL_138
```
---
### AccountWalletRegistry Integration
#### Issue: Cannot Link Smart Account
**Symptoms**:
- Error: "AccountWalletRegistryExtended: not a contract"
- Error: "AccountWalletRegistryExtended: zero smartAccount"
**Solutions**:
1. **Verify Smart Account**: Ensure address is a contract
```bash
cast code $SMART_ACCOUNT_ADDRESS --rpc-url $RPC_URL_138
```
2. **Check Permissions**: Verify caller has ACCOUNT_MANAGER_ROLE
```solidity
registry.hasRole(registry.ACCOUNT_MANAGER_ROLE(), caller)
```
3. **Check Address**: Ensure address is not zero address
---
#### Issue: isSmartAccount() Returns False
**Symptoms**:
- `isSmartAccount()` returns false for valid smart account
- Smart account not detected
**Solutions**:
1. **Verify Link**: Check if smart account was linked
```solidity
registry.isLinked(accountRefId, walletRefId)
```
2. **Check Mapping**: Verify `_isSmartAccount` mapping is set
3. **Re-link**: Try linking the smart account again
---
### Delegation Issues
#### Issue: Delegation Request Fails
**Symptoms**:
- Error: "User rejected"
- Error: "Permission denied"
**Solutions**:
1. **Check MetaMask**: Ensure MetaMask is unlocked
2. **Check Network**: Verify connected to ChainID 138
3. **Review Request**: Check delegation request details
4. **Try Again**: Retry after refresh
---
#### Issue: Delegation Not Working
**Symptoms**:
- dApp cannot execute transactions
- Error: "Delegation expired"
**Solutions**:
1. **Check Status**: Verify delegation is active
```typescript
const status = await kit.getDelegationStatus({
target: dAppAddress,
account: smartAccountAddress,
});
```
2. **Check Expiry**: Verify delegation hasn't expired
```typescript
if (status.expiry < Date.now()) {
// Delegation expired, request new one
}
```
3. **Check Permissions**: Verify required permissions are granted
4. **Revoke and Re-grant**: Try revoking and re-granting delegation
---
### Advanced Permissions Issues
#### Issue: Permission Request Denied
**Symptoms**:
- Permission request rejected
- Error: "Permission denied"
**Solutions**:
1. **Check MetaMask**: Ensure MetaMask is unlocked
2. **Review Request**: Check permission details
3. **Check Function**: Verify function selector is correct
4. **Try Again**: Retry after refresh
---
#### Issue: Permission Not Working
**Symptoms**:
- Permission granted but function fails
- Error: "Permission denied"
**Solutions**:
1. **Check Permission**: Verify permission is granted
```typescript
const hasPermission = await kit.hasPermission({
account: smartAccountAddress,
target: contractAddress,
functionSelector: functionSelector,
});
```
2. **Check Function Selector**: Verify selector matches
3. **Check Target**: Verify contract address is correct
4. **Revoke and Re-grant**: Try revoking and re-granting permission
---
### User Operations (Batch) Issues
#### Issue: Batch Operation Fails
**Symptoms**:
- Batch transaction fails
- Error: "User operation failed"
**Solutions**:
1. **Check Operations**: Verify all operations are valid
2. **Check Gas**: Ensure sufficient gas for batch
3. **Check Permissions**: Verify required permissions are granted
4. **Try Individually**: Test operations individually first
---
### Gas Abstraction Issues
#### Issue: Gas Abstraction Not Working
**Symptoms**:
- User still pays gas
- Error: "Paymaster not configured"
**Solutions**:
1. **Check Paymaster**: Verify Paymaster is deployed
```bash
cast code $PAYMASTER_ADDRESS --rpc-url $RPC_URL_138
```
2. **Check Configuration**: Verify Paymaster is configured in SDK
```typescript
const kit = new SmartAccountsKit({
paymasterAddress: '0x...', // Must be set
});
```
3. **Check Funding**: Verify Paymaster has funds
4. **Check Policy**: Verify Paymaster policy allows operation
---
## Debugging Tools
### Check Smart Account
```bash
# Check if address is a contract
cast code $SMART_ACCOUNT_ADDRESS --rpc-url $RPC_URL_138
# Check balance
cast balance $SMART_ACCOUNT_ADDRESS --rpc-url $RPC_URL_138
# Check nonce
cast nonce $SMART_ACCOUNT_ADDRESS --rpc-url $RPC_URL_138
```
### Check Delegation
```typescript
// Check delegation status
const status = await kit.getDelegationStatus({
target: dAppAddress,
account: smartAccountAddress,
});
console.log('Active:', status.active);
console.log('Expires:', status.expiry);
console.log('Permissions:', status.permissions);
```
### Check Permissions
```typescript
// Check permission
const hasPermission = await kit.hasPermission({
account: smartAccountAddress,
target: contractAddress,
functionSelector: functionSelector,
});
console.log('Has permission:', hasPermission);
```
---
## Getting Help
### Documentation
- [Smart Accounts User Guide](./SMART_ACCOUNTS_USER_GUIDE.md)
- [Smart Accounts Developer Guide](./SMART_ACCOUNTS_DEVELOPER_GUIDE.md)
- [Delegation Usage Guide](./DELEGATION_USAGE_GUIDE.md)
- [Advanced Permissions Guide](./ADVANCED_PERMISSIONS_GUIDE.md)
### Support Channels
1. **Check Documentation**: Review guides first
2. **Search Issues**: Check for similar issues
3. **Contact Support**: Reach out to support team
4. **Community**: Ask in community forums
---
## Prevention Tips
### Best Practices
1. **Test First**: Test on testnet before mainnet
2. **Check Balances**: Ensure sufficient funds
3. **Verify Contracts**: Check contract addresses
4. **Monitor Expiry**: Track delegation/permission expiry
5. **Review Permissions**: Review before granting
### Monitoring
1. **Transaction History**: Monitor transaction history
2. **Delegation Status**: Check active delegations
3. **Permission Status**: Check granted permissions
4. **Error Logs**: Review error logs regularly
---
**Last Updated**: 2026-01-26

440
docs/SMART_VAULT_COMPREHENSIVE_COMPARISON.md Normal file
View File

@@ -0,0 +1,440 @@
# Smart Vault System vs MetaMask Smart Accounts Kit - Comprehensive Comparison
**Date**: 2026-01-26
**Reference**: [MetaMask Smart Accounts Kit](https://docs.metamask.io/smart-accounts-kit#partner-integrations)
---
## Executive Summary
The Proxmox project contains a **Smart Vault System** for payment rail settlement, which is **fundamentally different** from MetaMask Smart Accounts Kit. However, they can be **complementary** and integrated together.
---
## System Overview
### Proxmox Smart Vault System
**Purpose**: Payment rail settlement and compliance for traditional financial systems.
**Components**:
1. **RailEscrowVault** (`0x609644D9858435f908A5B8528941827dDD13a346`)
- Escrows tokens for payment rail transfers
- Supports FEDWIRE, SWIFT, SEPA, RTGS
- Per-trigger escrow tracking
2. **AccountWalletRegistry** (`0xBeEF0128B7ff030e25beeda6Ff62f02041Dedbd0`)
- Maps fiat accounts (IBAN, ABA) to Web3 wallets
- Supports multiple wallet providers (MetaMask, Fireblocks)
- 1-to-many account-wallet mapping
3. **SettlementOrchestrator**
- Coordinates payment trigger lifecycle
- Validates compliance and policies
- Manages escrow lock/release
**Architecture**: Standard EOAs (Externally Owned Accounts) with escrow contracts
---
### MetaMask Smart Accounts Kit
**Purpose**: Programmable account behavior and granular permission sharing.
**Key Features**:
- ✅ **Smart Accounts**: ERC-4337 compatible programmable accounts
- ✅ **Delegation Framework**: Rule-based permission sharing
- ✅ **Advanced Permissions (ERC-7715)**: Fine-grained dApp permissions
- ✅ **User Operations**: Batch transactions
- ✅ **Gas Abstraction**: Pay gas in tokens or sponsor gas
- ✅ **Multi-Signature**: Multi-sig approvals
**Architecture**: Smart contract accounts with programmable logic
**Reference**: [MetaMask Smart Accounts Kit Documentation](https://docs.metamask.io/smart-accounts-kit#partner-integrations)
---
## Detailed Feature Comparison
### 1. Account Type
| Feature | Proxmox Smart Vault | MetaMask Smart Accounts Kit |
|---------|---------------------|----------------------------|
| **Account Type** | Standard EOAs | Smart Contract Accounts |
| **Programmability** | ❌ No | ✅ Yes |
| **Custom Logic** | ❌ No | ✅ Yes |
| **Upgradeability** | ❌ No | ✅ Yes (via proxy) |
### 2. Permission System
| Feature | Proxmox Smart Vault | MetaMask Smart Accounts Kit |
|---------|---------------------|----------------------------|
| **Delegation** | ❌ No | ✅ Yes (Delegation Framework) |
| **Advanced Permissions** | ❌ No | ✅ Yes (ERC-7715) |
| **Rule-Based Permissions** | ❌ No | ✅ Yes |
| **Permission Expiry** | ❌ No | ✅ Yes |
| **Role-Based Access** | ✅ Yes (AccessControl) | ✅ Yes (Delegation) |
### 3. Transaction Features
| Feature | Proxmox Smart Vault | MetaMask Smart Accounts Kit |
|---------|---------------------|----------------------------|
| **Batch Operations** | ❌ No | ✅ Yes (User Operations) |
| **Gas Abstraction** | ❌ No | ✅ Yes |
| **Transaction Batching** | ❌ No | ✅ Yes |
| **Multi-Signature** | ❌ No | ✅ Yes |
| **Account Abstraction** | ❌ No | ✅ Yes (ERC-4337) |
### 4. Payment Rail Features
| Feature | Proxmox Smart Vault | MetaMask Smart Accounts Kit |
|---------|---------------------|----------------------------|
| **Payment Rail Support** | ✅ Yes (FEDWIRE, SWIFT, SEPA) | ❌ No |
| **Escrow Management** | ✅ Yes (RailEscrowVault) | ❌ No |
| **Settlement Orchestration** | ✅ Yes | ❌ No |
| **Compliance Integration** | ✅ Yes | ❌ No |
| **Policy Enforcement** | ✅ Yes | ❌ No |
### 5. Account-Wallet Mapping
| Feature | Proxmox Smart Vault | MetaMask Smart Accounts Kit |
|---------|---------------------|----------------------------|
| **Fiat Account Mapping** | ✅ Yes (AccountWalletRegistry) | ❌ No |
| **Wallet Provider Support** | ✅ Yes (MetaMask, Fireblocks) | ✅ Yes (MetaMask) |
| **1-to-Many Mapping** | ✅ Yes | ❌ No |
| **Account Privacy** | ✅ Yes (Hashed refs) | ❌ No |
---
## Use Case Comparison
### Proxmox Smart Vault Use Cases
1. **Payment Rail Settlement**:
- Lock tokens for FEDWIRE transfer
- Lock tokens for SWIFT transfer
- Coordinate settlement lifecycle
- Enforce compliance and policies
2. **Account-Wallet Linking**:
- Link IBAN to MetaMask wallet
- Link ABA routing to wallet
- Track wallet providers
- Manage account-wallet relationships
3. **Compliance and Policy**:
- Check compliance registry
- Enforce policy manager rules
- Validate account eligibility
- Track regulated entities
### MetaMask Smart Accounts Kit Use Cases
1. **dApp Integration**:
- Execute transactions on behalf of users
- Request advanced permissions
- Batch multiple operations
- Abstract gas payments
2. **User Experience**:
- Programmable account behavior
- Delegation to dApps
- Gas abstraction
- Batch transactions
3. **Developer Features**:
- Smart account creation
- Delegation framework
- Permission management
- User operation batching
---
## Integration Opportunities
### Option 1: Deploy Smart Accounts Kit Alongside Smart Vault
**Architecture**:
```
┌─────────────────────┐
│ Fiat Account │
│ (IBAN/ABA) │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ AccountWalletRegistry│
└──────────┬──────────┘
│
├──► EOA Wallet (MetaMask)
│ └──► RailEscrowVault (Payment Rails)
│
└──► Smart Account (New)
├──► Delegation Framework
├──► Advanced Permissions
└──► User Operations (dApps)
```
**Benefits**:
- ✅ Keep existing payment rail system
- ✅ Add smart account capabilities
- ✅ Support both use cases
- ✅ Enhanced user experience
### Option 2: Enhance AccountWalletRegistry with Smart Accounts
**Implementation**:
1. Extend AccountWalletRegistry to support smart accounts
2. Auto-create smart accounts when linking wallets
3. Support both EOA and smart accounts
4. Use smart accounts for dApp interactions
5. Use EOAs for payment rails (if needed)
**Benefits**:
- ✅ Unified account management
- ✅ Seamless integration
- ✅ Backward compatible
- ✅ Enhanced capabilities
### Option 3: Hybrid Approach (Recommended)
**Implementation**:
1. **Payment Rails**: Continue using RailEscrowVault with EOAs
2. **dApp Interactions**: Use Smart Accounts Kit
3. **Account Management**: AccountWalletRegistry manages both
4. **Bridge**: SettlementOrchestrator can use either
**Benefits**:
- ✅ Best of both worlds
- ✅ Maintain existing functionality
- ✅ Add new capabilities
- ✅ Flexible architecture
---
## Implementation Plan
### Phase 1: Deploy Smart Accounts Kit
**Tasks**:
1. Install Smart Accounts Kit SDK
2. Deploy EntryPoint contract
3. Deploy AccountFactory contract
4. Deploy Paymaster contract (optional)
5. Configure for ChainID 138
**Files to Create**:
- `scripts/deploy-smart-accounts-kit.sh`
- `contracts/smart-accounts/DeploySmartAccounts.s.sol`
- `docs/SMART_ACCOUNTS_DEPLOYMENT.md`
### Phase 2: Integrate with AccountWalletRegistry
**Tasks**:
1. Extend AccountWalletRegistry interface
2. Add smart account creation on link
3. Support both EOA and smart accounts
4. Update API documentation
**Files to Create**:
- `contracts/emoney/AccountWalletRegistryExtended.sol`
- `docs/SMART_ACCOUNTS_ACCOUNT_WALLET_INTEGRATION.md`
### Phase 3: Add Delegation Framework
**Tasks**:
1. Implement delegation framework
2. Create delegation rules
3. Enable permission sharing
4. Test delegation flows
**Files to Create**:
- `docs/SMART_ACCOUNTS_DELEGATION.md`
- `examples/delegation-example.ts`
### Phase 4: Advanced Permissions (ERC-7715)
**Tasks**:
1. Implement ERC-7715 standard
2. Enable permission requests
3. Manage permission lifecycle
4. Test permission flows
**Files to Create**:
- `docs/SMART_ACCOUNTS_ADVANCED_PERMISSIONS.md`
- `examples/advanced-permissions-example.ts`
---
## Code Examples
### Current: AccountWalletRegistry
```solidity
// Link MetaMask EOA to fiat account
accountWalletRegistry.linkAccountToWallet(
keccak256("IBAN123"),
keccak256("0xWalletAddress"),
keccak256("METAMASK")
);
```
### Proposed: Smart Account Integration
```typescript
// Create smart account and link
const smartAccount = await smartAccountsKit.createAccount({
owner: userAddress,
});
await accountWalletRegistry.linkAccountToWallet(
keccak256("IBAN123"),
keccak256(abi.encodePacked(smartAccount.address)),
keccak256("METAMASK_SMART_ACCOUNT")
);
```
### Proposed: Delegation for Payment Rails
```typescript
// Delegate payment rail operations
const delegation = await smartAccountsKit.requestDelegation({
target: settlementOrchestratorAddress,
permissions: ['lock_escrow', 'release_escrow'],
expiry: Date.now() + 86400000, // 24 hours
});
```
---
## Partner Integration Opportunities
According to [MetaMask Smart Accounts Kit documentation](https://docs.metamask.io/smart-accounts-kit#partner-integrations), the following partners are integrated:
- **Scaffold-ETH 2**: Smart Accounts extension
- **Viem**: Smart Accounts support
- **Arbitrum**: Network support
- **permissionless.js**: Smart Accounts integration
- **Monad**: Testnet support
**ChainID 138 Integration**:
- Submit ChainID 138 for Smart Accounts Kit support
- Create partner integration guide
- Test with existing partners (Viem, permissionless.js)
---
## Benefits of Integration
### For Payment Rails
- ✅ **Keep Existing System**: RailEscrowVault continues to work
- ✅ **Enhanced Security**: Smart accounts for sensitive operations
- ✅ **Better Compliance**: Programmable compliance checks
- ✅ **Delegation**: Delegate payment operations securely
### For dApps
- ✅ **Better UX**: Gas abstraction, batch operations
- ✅ **Advanced Permissions**: Fine-grained permission control
- ✅ **Delegation**: Execute on behalf of users
- ✅ **Programmable**: Custom account behavior
### For Users
- ✅ **Flexibility**: Choose EOA or smart account
- ✅ **Better UX**: Gas abstraction, batch transactions
- ✅ **Security**: Delegation with expiry
- ✅ **Control**: Fine-grained permissions
---
## Recommended Approach
### Hybrid Architecture (Recommended)
1. **Payment Rails**: Use RailEscrowVault with EOAs (existing system)
2. **dApp Interactions**: Use Smart Accounts Kit (new capabilities)
3. **Account Management**: AccountWalletRegistry manages both
4. **Bridge**: Users can have both EOA and smart account linked
**Benefits**:
- ✅ Maintains existing payment rail functionality
- ✅ Adds smart account capabilities
- ✅ Flexible for different use cases
- ✅ Backward compatible
---
## Implementation Checklist
### Smart Accounts Kit Deployment
- [ ] Review MetaMask Smart Accounts Kit documentation
- [ ] Install SDK: `npm install @metamask/smart-accounts-kit`
- [ ] Deploy EntryPoint contract
- [ ] Deploy AccountFactory contract
- [ ] Deploy Paymaster contract (optional)
- [ ] Configure for ChainID 138
- [ ] Test smart account creation
### AccountWalletRegistry Integration
- [ ] Extend AccountWalletRegistry interface
- [ ] Add smart account creation function
- [ ] Support both EOA and smart accounts
- [ ] Update linking functions
- [ ] Test smart account linking
- [ ] Update API documentation
### Delegation Framework
- [ ] Implement delegation framework
- [ ] Create delegation rules
- [ ] Enable permission sharing
- [ ] Test delegation flows
- [ ] Create delegation examples
### Advanced Permissions
- [ ] Implement ERC-7715 standard
- [ ] Enable permission requests
- [ ] Manage permission lifecycle
- [ ] Test permission flows
- [ ] Create permission examples
---
## Files Created
1. **`docs/SMART_VAULT_VS_METAMASK_SMART_ACCOUNTS_COMPARISON.md`** - Initial comparison
2. **`docs/SMART_VAULT_COMPREHENSIVE_COMPARISON.md`** - This comprehensive comparison
3. **`scripts/deploy-smart-accounts-kit.sh`** - Deployment script
4. **`smart-accounts-kit-deployment/DEPLOYMENT_GUIDE.md`** - Deployment guide
5. **`smart-accounts-kit-deployment/ACCOUNT_WALLET_INTEGRATION.md`** - Integration guide
---
## Next Steps
1. **Review Comparison**: Understand differences and opportunities
2. **Deploy Smart Accounts Kit**: Deploy to ChainID 138
3. **Integrate with AccountWalletRegistry**: Extend existing system
4. **Test Integration**: Test all features
5. **Document**: Create user and developer guides
---
## Conclusion
The Proxmox Smart Vault System and MetaMask Smart Accounts Kit serve **different but complementary purposes**:
- **Smart Vault**: Payment rail settlement and compliance ✅
- **Smart Accounts Kit**: Programmable accounts and dApp integration ✅
**Recommended**: Deploy Smart Accounts Kit alongside Smart Vault system for enhanced capabilities while maintaining existing payment rail functionality.
---
**Last Updated**: 2026-01-26

411
docs/SMART_VAULT_VS_METAMASK_SMART_ACCOUNTS_COMPARISON.md Normal file
View File

@@ -0,0 +1,411 @@
# Smart Vault vs MetaMask Smart Accounts Kit - Comparison
**Date**: 2026-01-26
**Reference**: [MetaMask Smart Accounts Kit Documentation](https://docs.metamask.io/smart-accounts-kit#partner-integrations)
---
## Executive Summary
The Proxmox project contains **RailEscrowVault** and **AccountWalletRegistry** systems, which serve different purposes than MetaMask Smart Accounts Kit. This document compares the two systems and outlines integration opportunities.
---
## System Comparison
### MetaMask Smart Accounts Kit
**Purpose**: Enable programmable account behavior and granular permission sharing for MetaMask users.
**Key Features**:
- ✅ **Smart Accounts**: Programmable accounts with custom logic
- ✅ **Delegation Framework**: Rule-based permission sharing
- ✅ **Advanced Permissions (ERC-7715)**: Fine-grained permissions for dApps
- ✅ **User Operations**: Batch transactions and gas abstraction
- ✅ **Multi-Signature**: Multi-sig approvals
- ✅ **Gas Abstraction**: Pay gas in tokens or sponsor gas
**Use Cases**:
- Execute on behalf of users
- Batch multiple transactions
- Share permissions with dApps
- Programmable account behavior
---
### Proxmox Smart Vault System
**Components**:
#### 1. RailEscrowVault
**Purpose**: Holds tokens locked for outbound rail transfers (payment rails like FEDWIRE, SWIFT, SEPA).
**Key Features**:
- ✅ **Token Escrow**: Locks tokens for payment rail transfers
- ✅ **Per-Trigger Tracking**: Tracks escrow by trigger ID
- ✅ **Role-Based Access**: SETTLEMENT_OPERATOR_ROLE required
- ✅ **Lock/Release**: Lock tokens for settlement, release after completion
**Address**: `0x609644D9858435f908A5B8528941827dDD13a346`
**Use Cases**:
- Lock tokens for FEDWIRE transfers
- Lock tokens for SWIFT transfers
- Lock tokens for SEPA transfers
- Manage escrow for payment rails
#### 2. AccountWalletRegistry
**Purpose**: Maps regulated fiat accounts (IBAN, ABA) to Web3 wallets.
**Key Features**:
- ✅ **Account-Wallet Mapping**: Links fiat accounts to wallets
- ✅ **Provider Support**: Supports MetaMask, Fireblocks, etc.
- ✅ **1-to-Many Mapping**: One account can link to multiple wallets
- ✅ **Active/Inactive Links**: Can activate/deactivate links
- ✅ **Privacy**: Stores hashed references (no PII on-chain)
**Address**: `0xBeEF0128B7ff030e25beeda6Ff62f02041Dedbd0`
**Use Cases**:
- Link IBAN to MetaMask wallet
- Link ABA routing to wallet
- Track wallet providers
- Manage account-wallet relationships
#### 3. SettlementOrchestrator
**Purpose**: Coordinates trigger lifecycle and fund locking/release.
**Key Features**:
- ✅ **Trigger Validation**: Validates payment triggers
- ✅ **Compliance Checks**: Checks compliance registry
- ✅ **Policy Enforcement**: Enforces policy manager rules
- ✅ **Escrow Management**: Manages vault or lien escrow
- ✅ **Rail Integration**: Integrates with payment rails
**Use Cases**:
- Coordinate payment settlements
- Validate compliance
- Enforce policies
- Manage escrow lifecycle
---
## Feature Comparison Matrix
| Feature | MetaMask Smart Accounts Kit | Proxmox Smart Vault System |
|---------|----------------------------|---------------------------|
| **Programmable Accounts** | ✅ Yes (Smart Accounts) | ❌ No (Standard EOAs) |
| **Delegation Framework** | ✅ Yes (Rule-based) | ❌ No |
| **Advanced Permissions (ERC-7715)** | ✅ Yes | ❌ No |
| **User Operations** | ✅ Yes (Batch transactions) | ❌ No |
| **Gas Abstraction** | ✅ Yes | ❌ No |
| **Multi-Signature** | ✅ Yes | ❌ No |
| **Token Escrow** | ❌ No | ✅ Yes (RailEscrowVault) |
| **Account-Wallet Mapping** | ❌ No | ✅ Yes (AccountWalletRegistry) |
| **Payment Rail Integration** | ❌ No | ✅ Yes (SettlementOrchestrator) |
| **Compliance Integration** | ❌ No | ✅ Yes (ComplianceRegistry) |
| **Policy Enforcement** | ❌ No | ✅ Yes (PolicyManager) |
---
## Key Differences
### 1. Purpose
**MetaMask Smart Accounts Kit**:
- Focus: User experience and dApp integration
- Goal: Enable programmable accounts and permission sharing
- Target: End users and dApp developers
**Proxmox Smart Vault System**:
- Focus: Payment rail settlement and compliance
- Goal: Manage escrow for traditional payment rails
- Target: Financial institutions and regulated entities
### 2. Architecture
**MetaMask Smart Accounts Kit**:
- Smart contract accounts (ERC-4337 compatible)
- Delegation framework
- Permission system (ERC-7715)
- User operation batching
**Proxmox Smart Vault System**:
- Standard EOAs (Externally Owned Accounts)
- Escrow vault contracts
- Account-wallet registry
- Settlement orchestration
### 3. Use Cases
**MetaMask Smart Accounts Kit**:
- Execute transactions on behalf of users
- Batch multiple operations
- Share permissions with dApps
- Gas abstraction
**Proxmox Smart Vault System**:
- Lock tokens for payment rail transfers
- Map fiat accounts to wallets
- Coordinate payment settlements
- Enforce compliance and policies
---
## Integration Opportunities
### Option 1: Add MetaMask Smart Accounts Kit Support
**Benefits**:
- Enable programmable accounts for ChainID 138
- Support delegation and advanced permissions
- Enable gas abstraction
- Support user operation batching
**Implementation**:
1. Deploy MetaMask Smart Accounts Kit contracts
2. Integrate with existing AccountWalletRegistry
3. Add delegation framework
4. Support ERC-7715 Advanced Permissions
**Files to Create**:
- Smart Accounts deployment scripts
- Delegation integration guide
- Advanced Permissions setup
- Integration with AccountWalletRegistry
### Option 2: Enhance AccountWalletRegistry with Smart Account Features
**Benefits**:
- Add programmable behavior to registered wallets
- Enable delegation for payment rails
- Support batch operations
- Add permission framework
**Implementation**:
1. Extend AccountWalletRegistry to support smart accounts
2. Add delegation capabilities
3. Integrate with MetaMask Smart Accounts Kit
4. Support both standard and smart accounts
### Option 3: Hybrid Approach
**Benefits**:
- Keep existing RailEscrowVault for payment rails
- Add Smart Accounts for dApp interactions
- Support both use cases
**Implementation**:
1. Deploy MetaMask Smart Accounts Kit
2. Keep RailEscrowVault for payment rails
3. Use Smart Accounts for dApp interactions
4. Bridge between systems via AccountWalletRegistry
---
## Recommended Integration Path
### Phase 1: Deploy MetaMask Smart Accounts Kit
1. **Deploy Smart Accounts Contracts**:
- Deploy MetaMask Smart Accounts Kit contracts
- Configure for ChainID 138
- Set up delegation framework
2. **Integrate with AccountWalletRegistry**:
- Extend AccountWalletRegistry to support smart accounts
- Link smart accounts to fiat accounts
- Support both EOA and smart accounts
3. **Add Delegation Support**:
- Implement delegation framework
- Support rule-based permissions
- Enable dApp permissions
### Phase 2: Advanced Features
1. **ERC-7715 Advanced Permissions**:
- Implement Advanced Permissions standard
- Enable fine-grained dApp permissions
- Support permission requests from MetaMask
2. **Gas Abstraction**:
- Enable gas payment in tokens
- Support gas sponsorship
- Batch operations for efficiency
3. **User Operations**:
- Support user operation batching
- Enable transaction batching
- Optimize gas usage
---
## Integration Guide Structure
### 1. Smart Accounts Deployment
**File**: `docs/SMART_ACCOUNTS_DEPLOYMENT.md`
- Deploy MetaMask Smart Accounts Kit
- Configure for ChainID 138
- Set up delegation framework
- Test smart account creation
### 2. AccountWalletRegistry Integration
**File**: `docs/SMART_ACCOUNTS_ACCOUNT_WALLET_INTEGRATION.md`
- Extend AccountWalletRegistry
- Support smart account addresses
- Link smart accounts to fiat accounts
- Manage smart account lifecycle
### 3. Delegation Framework
**File**: `docs/SMART_ACCOUNTS_DELEGATION.md`
- Implement delegation framework
- Create delegation rules
- Enable permission sharing
- Test delegation flows
### 4. Advanced Permissions
**File**: `docs/SMART_ACCOUNTS_ADVANCED_PERMISSIONS.md`
- Implement ERC-7715
- Enable permission requests
- Manage permission lifecycle
- Test permission flows
---
## Code Examples
### Current: AccountWalletRegistry Usage
```solidity
// Link MetaMask wallet to fiat account
accountWalletRegistry.linkAccountToWallet(
keccak256("IBAN123"),
keccak256("0xWalletAddress"),
keccak256("METAMASK")
);
```
### Proposed: Smart Account Integration
```solidity
// Create smart account and link to fiat account
address smartAccount = smartAccountFactory.createAccount(userAddress);
accountWalletRegistry.linkAccountToWallet(
keccak256("IBAN123"),
keccak256(abi.encodePacked(smartAccount)),
keccak256("METAMASK_SMART_ACCOUNT")
);
```
### Proposed: Delegation Usage
```typescript
// Request delegation from user
const delegation = await smartAccountsKit.requestDelegation({
target: dAppAddress,
permissions: ['execute_transactions', 'batch_operations'],
expiry: Date.now() + 86400000, // 24 hours
});
```
---
## Benefits of Integration
### For Users
- ✅ **Programmable Accounts**: Custom account behavior
- ✅ **Gas Abstraction**: Pay gas in tokens
- ✅ **Batch Operations**: Multiple transactions in one
- ✅ **Permission Sharing**: Share permissions with dApps
### For dApps
- ✅ **Execute on Behalf**: Execute transactions for users
- ✅ **Advanced Permissions**: Fine-grained permission control
- ✅ **Better UX**: Batch operations, gas abstraction
- ✅ **Delegation**: Rule-based permission sharing
### For Payment Rails
- ✅ **Keep Existing System**: RailEscrowVault continues to work
- ✅ **Enhanced Capabilities**: Add smart account features
- ✅ **Better Integration**: Bridge traditional and Web3
- ✅ **Compliance**: Maintain compliance with smart accounts
---
## Implementation Checklist
### Phase 1: Smart Accounts Deployment
- [ ] Review MetaMask Smart Accounts Kit documentation
- [ ] Deploy Smart Accounts contracts to ChainID 138
- [ ] Configure delegation framework
- [ ] Test smart account creation
- [ ] Test delegation flows
### Phase 2: AccountWalletRegistry Integration
- [ ] Extend AccountWalletRegistry interface
- [ ] Add smart account support
- [ ] Update linking functions
- [ ] Test smart account linking
- [ ] Update API documentation
### Phase 3: Advanced Features
- [ ] Implement ERC-7715 Advanced Permissions
- [ ] Add gas abstraction support
- [ ] Enable user operation batching
- [ ] Test all features
- [ ] Create integration guides
---
## Partner Integrations
According to [MetaMask Smart Accounts Kit documentation](https://docs.metamask.io/smart-accounts-kit#partner-integrations), the following partners are integrated:
- **Scaffold-ETH 2**: Smart Accounts extension
- **Viem**: Smart Accounts support
- **Arbitrum**: Network support
- **permissionless.js**: Smart Accounts integration
- **Monad**: Testnet support
**ChainID 138 Integration Opportunity**:
- Submit ChainID 138 for Smart Accounts Kit support
- Create partner integration guide
- Test with existing partners
---
## Conclusion
The Proxmox Smart Vault system (RailEscrowVault, AccountWalletRegistry) serves a **different purpose** than MetaMask Smart Accounts Kit:
- **Smart Vault**: Payment rail settlement and compliance
- **Smart Accounts Kit**: Programmable accounts and dApp integration
**However**, they can be **complementary**:
- Smart Vault handles payment rails
- Smart Accounts Kit handles dApp interactions
- AccountWalletRegistry bridges both systems
**Recommended Action**: Deploy MetaMask Smart Accounts Kit alongside existing Smart Vault system for enhanced capabilities.
---
**Last Updated**: 2026-01-26

307
docs/SSL_CERTIFICATE_SETUP.md Normal file
View File

@@ -0,0 +1,307 @@
# SSL Certificate Setup Guide
Complete guide for configuring SSL certificates for ChainID 138 MetaMask integration endpoints.
## Overview
SSL certificates are required for HTTPS endpoints (RPC, explorer) to ensure secure connections from MetaMask.
## Options
### Option 1: Cloudflare SSL (Recommended)
**Benefits**:
- Free SSL certificates
- Automatic provisioning
- Auto-renewal
- DDoS protection included
**Setup**:
1. Enable Cloudflare proxy (orange cloud)
2. Set SSL/TLS mode to "Full" or "Full (strict)"
3. SSL certificates are automatically provisioned
4. Certificates auto-renew
**Configuration**:
- Go to Cloudflare Dashboard → SSL/TLS
- Set encryption mode: "Full (strict)"
- Enable "Always Use HTTPS"
- Enable "Automatic HTTPS Rewrites"
---
### Option 2: Let's Encrypt
**Benefits**:
- Free SSL certificates
- Widely trusted
- 90-day validity
**Setup**:
```bash
# Install certbot
sudo apt-get update
sudo apt-get install certbot
# Obtain certificate for RPC endpoint
sudo certbot certonly --standalone -d rpc.d-bis.org
# Obtain certificate for explorer
sudo certbot certonly --standalone -d explorer.d-bis.org
# Auto-renewal setup
sudo certbot renew --dry-run
```
**Nginx Configuration**:
```nginx
server {
listen 443 ssl http2;
server_name rpc.d-bis.org;
ssl_certificate /etc/letsencrypt/live/rpc.d-bis.org/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/rpc.d-bis.org/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers HIGH:!aNULL:!MD5;
# ... rest of configuration
}
```
---
### Option 3: Custom SSL Certificate
**Use Case**: Enterprise or custom requirements
**Providers**:
- DigiCert
- GlobalSign
- Sectigo
- GoDaddy
**Setup**:
1. Purchase SSL certificate
2. Generate CSR (Certificate Signing Request)
3. Submit CSR to provider
4. Install certificate
5. Configure web server
---
## Cloudflare SSL Configuration
### Step 1: Enable SSL/TLS
1. Go to Cloudflare Dashboard
2. Select domain `d-bis.org`
3. Go to SSL/TLS
4. Set encryption mode to "Full (strict)"
### Step 2: Configure SSL Settings
**SSL/TLS encryption mode**: Full (strict)
**Always Use HTTPS**: On
**Automatic HTTPS Rewrites**: On
**Minimum TLS Version**: TLS 1.2
**Opportunistic Encryption**: On
**TLS 1.3**: On
### Step 3: Verify SSL
```bash
# Test SSL certificate
openssl s_client -connect rpc.d-bis.org:443 -servername rpc.d-bis.org
# Check certificate details
echo | openssl s_client -connect rpc.d-bis.org:443 2>/dev/null | openssl x509 -noout -text
```
---
## Let's Encrypt Setup
### Automated Setup Script
```bash
#!/bin/bash
# Automated Let's Encrypt SSL setup for ChainID 138 endpoints
DOMAINS=(
"rpc.d-bis.org"
"rpc2.d-bis.org"
"explorer.d-bis.org"
)
EMAIL="admin@d-bis.org"
# Install certbot
sudo apt-get update
sudo apt-get install -y certbot
# Obtain certificates
for domain in "${DOMAINS[@]}"; do
echo "Obtaining certificate for $domain..."
sudo certbot certonly \
--standalone \
--non-interactive \
--agree-tos \
--email "$EMAIL" \
-d "$domain"
done
# Setup auto-renewal
sudo systemctl enable certbot.timer
sudo systemctl start certbot.timer
echo "SSL certificates obtained and auto-renewal configured!"
```
### Nginx SSL Configuration
```nginx
# SSL Configuration for RPC endpoint
server {
listen 443 ssl http2;
server_name rpc.d-bis.org;
# SSL Certificate
ssl_certificate /etc/letsencrypt/live/rpc.d-bis.org/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/rpc.d-bis.org/privkey.pem;
# SSL Protocols
ssl_protocols TLSv1.2 TLSv1.3;
# SSL Ciphers
ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384';
ssl_prefer_server_ciphers on;
# SSL Session
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 10m;
# Security Headers
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-Content-Type-Options "nosniff" always;
# ... rest of configuration
}
# HTTP to HTTPS redirect
server {
listen 80;
server_name rpc.d-bis.org;
return 301 https://$server_name$request_uri;
}
```
---
## Certificate Verification
### Test SSL Certificate
```bash
# Test certificate validity
openssl s_client -connect rpc.d-bis.org:443 -servername rpc.d-bis.org < /dev/null
# Check certificate expiration
echo | openssl s_client -connect rpc.d-bis.org:443 2>/dev/null | openssl x509 -noout -dates
# Check certificate chain
openssl s_client -connect rpc.d-bis.org:443 -showcerts
# Test from browser
curl -vI https://rpc.d-bis.org
```
### Expected Results
- ✅ Certificate is valid
- ✅ Certificate chain is complete
- ✅ Certificate matches domain
- ✅ Certificate is not expired
- ✅ HTTPS redirect works
---
## Auto-Renewal
### Let's Encrypt Auto-Renewal
```bash
# Test renewal
sudo certbot renew --dry-run
# Enable auto-renewal (systemd timer)
sudo systemctl enable certbot.timer
sudo systemctl start certbot.timer
# Check timer status
sudo systemctl status certbot.timer
```
### Cloudflare Auto-Renewal
Cloudflare automatically renews certificates. No action needed.
---
## Troubleshooting
### Certificate Not Working
1. Check certificate is installed correctly
2. Verify certificate matches domain
3. Check certificate expiration
4. Verify web server configuration
5. Check firewall rules
### Mixed Content Warnings
1. Ensure all resources use HTTPS
2. Update HTTP links to HTTPS
3. Use relative URLs where possible
4. Enable HSTS header
### Certificate Chain Issues
1. Verify intermediate certificates are included
2. Check certificate chain is complete
3. Test with SSL Labs: https://www.ssllabs.com/ssltest/
---
## Security Best Practices
1. **Use Strong Ciphers**: Only TLS 1.2 and 1.3
2. **Enable HSTS**: Strict Transport Security
3. **Regular Updates**: Keep certificates updated
4. **Monitor Expiration**: Set up expiration alerts
5. **Use Full Chain**: Include intermediate certificates
---
## Checklist
- [ ] SSL certificate obtained
- [ ] Certificate installed on server
- [ ] Web server configured for SSL
- [ ] HTTPS redirect configured
- [ ] Certificate verified
- [ ] Auto-renewal configured
- [ ] Security headers configured
- [ ] HSTS enabled
- [ ] Certificate tested from browser
- [ ] Certificate tested from MetaMask
---
**Last Updated**: 2026-01-26

306
docs/TESTING_GUIDE.md Normal file
View File

@@ -0,0 +1,306 @@
# Smart Accounts Testing Guide
**Date**: 2026-01-26
**Network**: ChainID 138 (SMOM-DBIS-138)
---
## Overview
This guide explains how to test Smart Accounts Kit integration on ChainID 138.
---
## Test Structure
### Unit Tests (Foundry)
Located in `test/smart-accounts/`:
```
test/smart-accounts/
├── AccountWalletRegistryExtendedTest.t.sol # Extended registry tests
└── (Additional test files to be created)
```
### Integration Tests (TypeScript/JavaScript)
Located in `test/`:
```
test/
└── smart-accounts-integration.test.ts # Integration tests
```
---
## Running Tests
### Unit Tests (Foundry)
```bash
# Run all Smart Accounts tests
forge test --match-path test/smart-accounts/** -vv
# Run specific test file
forge test --match-path test/smart-accounts/AccountWalletRegistryExtendedTest.t.sol -vv
# Run with gas reporting
forge test --match-path test/smart-accounts/** --gas-report
# Run with coverage
forge coverage --match-path test/smart-accounts/**
```
### Integration Tests
```bash
# Install dependencies
npm install
# Run integration tests
npm test
# Run with coverage
npm test -- --coverage
```
---
## Test Categories
### 1. Unit Tests
**AccountWalletRegistryExtended**:
- Link smart account
- Check if smart account
- Support both EOA and smart accounts
- Role-based access control
- Factory and EntryPoint configuration
**Run**:
```bash
forge test --match-contract AccountWalletRegistryExtendedTest -vv
```
### 2. Integration Tests
**Smart Account Creation**:
- Create smart account
- Create with salt
- Verify address format
**Delegation**:
- Request delegation
- Check delegation status
- Revoke delegation
- Test expiry
**Advanced Permissions**:
- Request permission
- Check permission
- Revoke permission
**User Operations**:
- Batch operations
- Execute batch
- Gas estimation
**Run**:
```bash
npm test -- smart-accounts-integration
```
### 3. End-to-End Tests
**Complete Flows**:
- Create smart account → Link to fiat account → Use for payment rails
- Create smart account → Grant delegation → dApp executes transactions
- Create smart account → Grant permissions → Execute functions
**Run**:
```bash
npm test -- e2e
```
---
## Writing Tests
### Foundry Test Example
```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
import {Test} from "forge-std/Test.sol";
import {AccountWalletRegistryExtended} from "../../contracts/smart-accounts/AccountWalletRegistryExtended.sol";
contract MyTest is Test {
AccountWalletRegistryExtended public registry;
function setUp() public {
// Setup test environment
registry = new AccountWalletRegistryExtended(...);
}
function test_myFunction() public {
// Arrange
// Act
// Assert
}
}
```
### Integration Test Example
```typescript
import { SmartAccountsKit } from '@metamask/smart-accounts-kit';
describe('My Feature', () => {
it('should work correctly', async () => {
const kit = new SmartAccountsKit({ ... });
const result = await kit.someFunction();
expect(result).toBeDefined();
});
});
```
---
## Test Data
### Test Addresses
```typescript
const TEST_ADDRESSES = {
admin: '0x...',
accountManager: '0x...',
smartAccountFactory: '0x...',
entryPoint: '0x...',
testUser: '0x...',
testSmartAccount: '0x...',
};
```
### Test Configuration
```typescript
const TEST_CONFIG = {
chainId: 138,
rpcUrl: process.env.RPC_URL_138 || 'http://192.168.11.211:8545',
entryPointAddress: process.env.ENTRY_POINT || '0x...',
accountFactoryAddress: process.env.ACCOUNT_FACTORY || '0x...',
};
```
---
## Test Coverage Goals
### Unit Tests
- ✅ AccountWalletRegistryExtended: 100%
- ⏳ Smart Account creation: 90%+
- ⏳ Delegation framework: 90%+
- ⏳ Advanced Permissions: 90%+
### Integration Tests
- ⏳ Smart Account creation: 100%
- ⏳ Delegation flows: 100%
- ⏳ Permission flows: 100%
- ⏳ User operations: 100%
### End-to-End Tests
- ⏳ Complete payment rail flow: 100%
- ⏳ Complete dApp interaction flow: 100%
- ⏳ Hybrid EOA + smart account flow: 100%
---
## Continuous Integration
### GitHub Actions Example
```yaml
name: Smart Accounts Tests
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: foundry-actions/setup-foundry@v1
- run: forge test --match-path test/smart-accounts/**
- run: npm test
```
---
## Debugging Tests
### Foundry Debugging
```bash
# Run with maximum verbosity
forge test --match-path test/smart-accounts/** -vvvv
# Run specific test
forge test --match-test test_linkSmartAccount -vvvv
# Use debugger
forge test --debug test_linkSmartAccount
```
### Integration Test Debugging
```bash
# Run with debug output
DEBUG=* npm test
# Run single test
npm test -- --testNamePattern="should create smart account"
```
---
## Best Practices
### 1. Test Isolation
- Each test should be independent
- Use `setUp()` for common setup
- Clean up after tests
### 2. Test Coverage
- Aim for 90%+ coverage
- Test happy paths
- Test error cases
- Test edge cases
### 3. Test Naming
- Use descriptive names
- Follow pattern: `test_<functionality>`
- Group related tests
### 4. Assertions
- Use specific assertions
- Check return values
- Verify events emitted
- Check state changes
---
## Resources
- [Foundry Testing Documentation](https://book.getfoundry.sh/forge/tests)
- [Jest Documentation](https://jestjs.io/docs/getting-started)
- [Smart Accounts Developer Guide](./SMART_ACCOUNTS_DEVELOPER_GUIDE.md)
---
**Last Updated**: 2026-01-26

148
docs/UPGRADE_PROCEDURES.md Normal file
View File

@@ -0,0 +1,148 @@
# Upgrade Procedures - Smart Accounts
**Date**: 2026-01-26
**Network**: ChainID 138 (SMOM-DBIS-138)
---
## Overview
This guide explains upgrade procedures for Smart Accounts contracts and configuration.
---
## Contract Upgrades
### AccountWalletRegistryExtended
**Upgrade Type**: Proxy pattern (if using upgradeable proxy)
**Procedure**:
1. Deploy new implementation
2. Propose upgrade via governance
3. Wait for approval
4. Execute upgrade
5. Verify functionality
**Rollback**:
- Keep previous implementation
- Can rollback if issues occur
---
## Configuration Upgrades
### Smart Accounts Kit SDK
**Upgrade Steps**:
1. Update package.json
2. Run `npm install`
3. Update configuration if needed
4. Test new version
5. Deploy to production
**Version Compatibility**:
- Check SDK changelog
- Review breaking changes
- Update code if needed
---
## Feature Upgrades
### Adding New Features
**Process**:
1. Deploy new contracts
2. Update configuration
3. Update documentation
4. Test thoroughly
5. Deploy to production
### Enabling Features
**Example**: Enable gas abstraction
1. Deploy Paymaster contract
2. Update configuration
3. Update SDK configuration
4. Test gas abstraction
5. Enable for users
---
## Upgrade Checklist
### Pre-Upgrade
- [ ] Review upgrade notes
- [ ] Backup current configuration
- [ ] Test on testnet
- [ ] Prepare rollback plan
### Upgrade
- [ ] Deploy new contracts
- [ ] Update configuration
- [ ] Update SDK
- [ ] Test functionality
- [ ] Monitor for issues
### Post-Upgrade
- [ ] Verify all features work
- [ ] Monitor metrics
- [ ] Check error logs
- [ ] Update documentation
---
## Rollback Procedures
### Contract Rollback
1. Identify issue
2. Pause new implementation
3. Rollback to previous version
4. Verify rollback success
5. Investigate issue
### Configuration Rollback
1. Restore previous configuration
2. Restart services
3. Verify functionality
4. Investigate issue
---
## Best Practices
### 1. Staged Rollout
- Deploy to testnet first
- Deploy to staging
- Deploy to production gradually
### 2. Monitoring
- Monitor during upgrade
- Watch for errors
- Track metrics
### 3. Communication
- Notify users of upgrades
- Document changes
- Provide support
---
## Resources
- [Deployment Checklist](./DEPLOYMENT_CHECKLIST.md)
- [Troubleshooting Guide](./SMART_ACCOUNTS_TROUBLESHOOTING.md)
---
**Last Updated**: 2026-01-26

483
docs/USER_TESTING_PLAN.md Normal file
View File

@@ -0,0 +1,483 @@
# MetaMask Integration User Testing Plan
Comprehensive user testing plan for MetaMask integration with ChainID 138.
## Overview
This plan outlines user testing procedures to validate MetaMask integration functionality, user experience, and identify issues before public release.
## Testing Objectives
1. **Functionality Testing**: Verify all features work correctly
2. **User Experience Testing**: Validate ease of use
3. **Compatibility Testing**: Test across browsers and devices
4. **Performance Testing**: Verify response times and reliability
5. **Security Testing**: Validate security measures
---
## Test Scenarios
### Scenario 1: Network Addition
**Objective**: Test adding ChainID 138 to MetaMask
**Steps**:
1. Open MetaMask extension
2. Click "Add Network" or use programmatic addition
3. Verify network details are correct
4. Add network
5. Verify network appears in network list
**Expected Results**:
- ✅ Network added successfully
- ✅ Network details are correct
- ✅ Network appears in list
- ✅ Can switch to network
**Test Cases**:
- [ ] Add network manually
- [ ] Add network programmatically
- [ ] Verify network details
- [ ] Switch to network
- [ ] Verify RPC connection works
---
### Scenario 2: Network Switching
**Objective**: Test switching to ChainID 138
**Steps**:
1. Open MetaMask
2. Click network dropdown
3. Select "DeFi Oracle Meta Mainnet"
4. Verify network switches
5. Verify balance displays
**Expected Results**:
- ✅ Network switches successfully
- ✅ Balance displays correctly
- ✅ RPC connection works
- ✅ Transactions can be sent
**Test Cases**:
- [ ] Switch from Ethereum to ChainID 138
- [ ] Switch from other network to ChainID 138
- [ ] Verify balance updates
- [ ] Verify transaction history
---
### Scenario 3: Token Addition
**Objective**: Test adding tokens to MetaMask
**Steps**:
1. Connect to ChainID 138
2. Click "Import tokens"
3. Enter token address (cUSDT)
4. Verify token details auto-fill
5. Add token
6. Verify token appears in wallet
**Expected Results**:
- ✅ Token details auto-fill correctly
- ✅ Decimals are correct (6 for cUSDT)
- ✅ Token appears in wallet
- ✅ Balance displays correctly
**Test Cases**:
- [ ] Add cUSDT (6 decimals)
- [ ] Add cUSDC (6 decimals)
- [ ] Add WETH (18 decimals)
- [ ] Verify decimals display correctly
- [ ] Verify token logos display
---
### Scenario 4: Token Transfer
**Objective**: Test sending tokens
**Steps**:
1. Connect to ChainID 138
2. Select token (cUSDT)
3. Click "Send"
4. Enter recipient address
5. Enter amount
6. Confirm transaction
7. Verify transaction succeeds
**Expected Results**:
- ✅ Transaction is created
- ✅ Gas estimation works
- ✅ Transaction is confirmed
- ✅ Balance updates correctly
- ✅ Transaction appears in history
**Test Cases**:
- [ ] Send cUSDT
- [ ] Send cUSDC
- [ ] Send WETH
- [ ] Send ETH (native)
- [ ] Verify transaction on explorer
---
### Scenario 5: Contract Interaction
**Objective**: Test interacting with smart contracts
**Steps**:
1. Connect to ChainID 138
2. Navigate to dApp
3. Connect wallet
4. Execute contract function
5. Confirm transaction
6. Verify transaction succeeds
**Expected Results**:
- ✅ Wallet connects successfully
- ✅ Contract interaction works
- ✅ Transaction is confirmed
- ✅ State updates correctly
**Test Cases**:
- [ ] Interact with token contract
- [ ] Interact with DEX contract
- [ ] Interact with bridge contract
- [ ] Verify gas estimation
- [ ] Verify transaction execution
---
### Scenario 6: Token List Import
**Objective**: Test importing token list
**Steps**:
1. Open MetaMask Settings
2. Navigate to Security & Privacy
3. Scroll to Token Lists
4. Add custom token list URL
5. Verify tokens appear
6. Verify token metadata is correct
**Expected Results**:
- ✅ Token list imports successfully
- ✅ Tokens appear in wallet
- ✅ Token metadata is correct
- ✅ Token logos display
**Test Cases**:
- [ ] Import token list from URL
- [ ] Verify all tokens appear
- [ ] Verify token metadata
- [ ] Verify token logos
- [ ] Verify decimals are correct
---
## Browser Testing
### Desktop Browsers
- [ ] Chrome (MetaMask Extension)
- [ ] Firefox (MetaMask Extension)
- [ ] Edge (MetaMask Extension)
- [ ] Brave (MetaMask Extension)
### Mobile
- [ ] iOS (MetaMask Mobile)
- [ ] Android (MetaMask Mobile)
---
## Device Testing
### Desktop
- [ ] Windows 10/11
- [ ] macOS
- [ ] Linux
### Mobile
- [ ] iPhone (iOS 14+)
- [ ] Android Phone (Android 10+)
---
## User Personas
### Persona 1: Crypto Novice
**Characteristics**:
- First time using MetaMask
- Limited crypto knowledge
- Needs clear instructions
**Test Focus**:
- Ease of network addition
- Clarity of instructions
- Error messages
- Help documentation
### Persona 2: Experienced User
**Characteristics**:
- Regular MetaMask user
- Familiar with multiple networks
- Technical knowledge
**Test Focus**:
- Speed of setup
- Feature completeness
- Advanced features
- Developer tools
### Persona 3: Developer
**Characteristics**:
- Building dApps
- Technical expertise
- Needs SDK/docs
**Test Focus**:
- SDK functionality
- Documentation quality
- Integration examples
- API completeness
---
## Test Checklist
### Pre-Testing
- [ ] Test environment set up
- [ ] Test accounts prepared
- [ ] Test tokens available
- [ ] Test network accessible
- [ ] Test documentation ready
### Functionality
- [ ] Network addition works
- [ ] Network switching works
- [ ] Token addition works
- [ ] Token transfer works
- [ ] Contract interaction works
- [ ] Token list import works
### User Experience
- [ ] Instructions are clear
- [ ] Error messages are helpful
- [ ] Loading states are shown
- [ ] Success feedback is provided
- [ ] Navigation is intuitive
### Compatibility
- [ ] Works on Chrome
- [ ] Works on Firefox
- [ ] Works on Edge
- [ ] Works on Mobile
- [ ] Works on different OS
### Performance
- [ ] Network addition is fast (<5s)
- [ ] Network switching is fast (<3s)
- [ ] Token addition is fast (<3s)
- [ ] Balance updates quickly
- [ ] Transactions confirm quickly
### Security
- [ ] Network details are verified
- [ ] Token addresses are verified
- [ ] Transactions are secure
- [ ] No phishing warnings
- [ ] SSL certificates are valid
---
## Test Data
### Test Accounts
- **Account 1**: Test account with ETH balance
- **Account 2**: Test account with token balances
- **Account 3**: Test account for contract interactions
### Test Tokens
- **cUSDT**: 20,000,000 tokens
- **cUSDC**: 20,000,000 tokens
- **WETH**: 10 tokens
- **LINK**: 100 tokens
### Test Addresses
- **Recipient 1**: `0x4207aA9aC89B8bF4795dbAbBbE17fdd224E7947C`
- **Recipient 2**: `0x4A666F96fC8764181194447A7dFdb7d471b301C8`
---
## Bug Reporting
### Bug Report Template
```markdown
## Bug Report
**Title**: [Brief description]
**Severity**: [Critical/High/Medium/Low]
**Steps to Reproduce**:
1. Step 1
2. Step 2
3. Step 3
**Expected Behavior**:
[What should happen]
**Actual Behavior**:
[What actually happens]
**Environment**:
- Browser: [Chrome/Firefox/etc]
- OS: [Windows/macOS/Linux]
- MetaMask Version: [Version]
- ChainID 138 SDK Version: [Version]
**Screenshots**:
[If applicable]
**Console Errors**:
[If applicable]
**Additional Notes**:
[Any other relevant information]
```
---
## Test Results Template
```markdown
# User Testing Results
**Date**: [Date]
**Tester**: [Name]
**Browser**: [Browser]
**OS**: [OS]
## Test Results
### Scenario 1: Network Addition
- Status: [Pass/Fail]
- Notes: [Notes]
### Scenario 2: Network Switching
- Status: [Pass/Fail]
- Notes: [Notes]
[... continue for all scenarios]
## Issues Found
1. [Issue description]
2. [Issue description]
## Recommendations
1. [Recommendation]
2. [Recommendation]
```
---
## Success Criteria
### Must Have (Critical)
- ✅ Network can be added
- ✅ Network can be switched to
- ✅ Tokens can be added
- ✅ Tokens display correctly
- ✅ Transactions can be sent
- ✅ No critical bugs
### Should Have (Important)
- ✅ Token list import works
- ✅ Token logos display
- ✅ Error messages are clear
- ✅ Performance is acceptable
- ✅ Works on all major browsers
### Nice to Have (Optional)
- ✅ Advanced features work
- ✅ Developer tools work
- ✅ Documentation is complete
- ✅ Examples are working
---
## Testing Schedule
### Week 1: Internal Testing
- Developer testing
- Functionality verification
- Bug fixing
### Week 2: Beta Testing
- Limited user testing
- Feedback collection
- Issue resolution
### Week 3: Public Testing
- Open beta testing
- Community feedback
- Final adjustments
### Week 4: Launch
- Production release
- Monitoring
- Support
---
## Post-Testing
### Analysis
- Analyze test results
- Identify common issues
- Prioritize fixes
- Update documentation
### Improvements
- Fix identified bugs
- Improve user experience
- Update documentation
- Enhance features
### Documentation
- Update user guides
- Update developer docs
- Create FAQ
- Create troubleshooting guide
---
**Last Updated**: 2026-01-26