diff --git a/README.md b/README.md index af6336a..2d75bb4 100644 --- a/README.md +++ b/README.md @@ -79,6 +79,10 @@ bunx skills add BankrBot/claude-plugins - Node.js 20+ - USDC on Base (for x402 payments) +## Community Examples + +See [community-examples/](./community-examples/) for real-world examples of Bankr workflows contributed by the community. + ## Links - [Bankr](https://bankr.bot) diff --git a/community-examples/README.md b/community-examples/README.md new file mode 100644 index 0000000..cf73168 --- /dev/null +++ b/community-examples/README.md @@ -0,0 +1,39 @@ +# Community Examples + +Community-contributed examples showcasing Bankr's capabilities for various Web3 workflows. + +## ENS Registration + +**Complete workflow for registering .eth names and deploying to IPFS** + +Register ENS names via Bankr's natural language interface. Includes primary name setup on L1/L2, subdomain creation, and IPFS content deployment. + +[View Example →](./ens-register/) + +**Features:** +- Register .eth names (automatic commit-reveal) +- Set primary names on Ethereum, Base, Arbitrum, Optimism +- Deploy static sites to IPFS + ENS +- Comprehensive troubleshooting guide + +**Example:** +```bash +./bankr.sh "register my-agent.eth for 1 year" +./bankr.sh "set my primary ENS name to my-agent.eth on ethereum" +./bankr.sh "create subdomain dashboard.my-agent.eth" +./bankr.sh "set contenthash for dashboard.my-agent.eth to ipfs://QmCID" +``` + +**Created by:** Cruller (@cruller_donut), DonutDAO + +--- + +## Contributing + +Have an example showcasing Bankr? Submit a PR! + +Guidelines: +- Complete, tested workflow +- Clear documentation +- Real-world use case +- MIT licensed diff --git a/community-examples/ens-register/INSTALL.md b/community-examples/ens-register/INSTALL.md new file mode 100644 index 0000000..ac1eded --- /dev/null +++ b/community-examples/ens-register/INSTALL.md @@ -0,0 +1,239 @@ +# Installation Guide + +## Quick Install + +### Method 1: Git Clone (Recommended) + +```bash +cd ~/.openclaw/skills +git clone https://github.com/cruller-agent/ens-register-skill.git ens-register +``` + +### Method 2: Download Package + +```bash +# Download the .skill package +wget https://github.com/cruller-agent/ens-register-skill/releases/latest/download/ens-register.skill + +# Move to skills directory +mv ens-register.skill ~/.openclaw/skills/ + +# Extract +cd ~/.openclaw/skills +unzip ens-register.skill +``` + +### Method 3: Via ClawdHub (Coming Soon) + +```bash +clawdhub install ens-register +``` + +## Prerequisites + +### 1. Bankr Skill + +This skill requires the Bankr skill for natural language crypto operations. + +**Check if installed:** +```bash +ls ~/.openclaw/skills/bankr +``` + +**If not installed:** +- Follow Bankr installation guide +- Configure with your API key + +### 2. ETH on Ethereum Mainnet + +Registration costs ~0.003 ETH ($6-7): +- Registration fee: ~0.002 ETH ($5) +- Gas: ~0.001 ETH ($2) + +**Check balance:** +```bash +cd ~/.openclaw/skills/bankr && ./scripts/bankr.sh "what's my ethereum balance?" +``` + +**If you need ETH:** +```bash +# Bridge from Base (cheaper) +./scripts/bankr.sh "bridge 0.005 ETH from base to ethereum" + +# Or buy on exchange and withdraw to Ethereum mainnet +``` + +### 3. IPFS (Optional) + +Only needed if deploying content to IPFS + ENS. + +**Install IPFS Desktop:** https://docs.ipfs.tech/install/ipfs-desktop/ + +**Or command line:** +```bash +# macOS +brew install ipfs + +# Linux +wget https://dist.ipfs.tech/kubo/v0.25.0/kubo_v0.25.0_linux-amd64.tar.gz +tar -xvzf kubo_v0.25.0_linux-amd64.tar.gz +cd kubo && sudo bash install.sh + +# Initialize and start +ipfs init +ipfs daemon +``` + +## Verify Installation + +```bash +# Check skill is present +ls ~/.openclaw/skills/ens-register/SKILL.md + +# Test Bankr is working +cd ~/.openclaw/skills/bankr +./scripts/bankr.sh "what chains do you support?" +``` + +## First Use + +### 1. Check Name Availability + +```bash +cd ~/.openclaw/skills/bankr +./scripts/bankr.sh "is my-agent.eth available?" +``` + +### 2. Register Your Name + +```bash +./scripts/bankr.sh "register my-agent.eth for 1 year" +``` + +This will: +1. Submit commit transaction +2. Wait ~1 minute +3. Submit register transaction +4. Complete registration + +**Time:** ~5 minutes +**Cost:** ~0.003 ETH ($6-7) + +### 3. Set Primary Name + +```bash +./scripts/bankr.sh "set my primary ENS name to my-agent.eth on ethereum" +``` + +Now your address shows as `my-agent.eth` instead of `0x123...` in: +- Etherscan +- Wallets (MetaMask, Rainbow) +- dApps + +## Next Steps + +### Deploy Dashboard to ENS + +```bash +# 1. Build your site +cd /path/to/your/site +npm run build + +# 2. Upload to IPFS +ipfs add -r ./build +# Copy the CID (starts with Qm or bafy) + +# 3. Create subdomain +cd ~/.openclaw/skills/bankr +./scripts/bankr.sh "create subdomain dashboard.my-agent.eth" + +# 4. Link to IPFS +./scripts/bankr.sh "set contenthash for dashboard.my-agent.eth to ipfs://YOUR_CID" + +# 5. Access +open https://dashboard.my-agent.eth.limo/ +``` + +### Set Primary Name on L2 + +Cheaper gas, better UX on Base/Arbitrum: + +```bash +# Base +./scripts/bankr.sh "set my primary ENS name to my-agent.eth on base" + +# Arbitrum +./scripts/bankr.sh "set my primary ENS name to my-agent.eth on arbitrum" +``` + +Cost: ~$0.01 per L2 + +## Troubleshooting + +### "Bankr not found" + +**Solution:** Install Bankr skill first. This skill depends on it. + +### "Insufficient funds" + +**Check balance:** +```bash +./scripts/bankr.sh "what's my ethereum balance?" +``` + +**Need at least 0.003 ETH** for registration + gas. + +### "Name not available" + +**Check expiry:** https://app.ens.domains/YOURNAME.eth + +**Try variations:** +- `my-agent.eth` → `myagent.eth` +- `agent-name.eth` → `agent-ai.eth` +- Use subdomains if you own another name + +### More Help + +See detailed troubleshooting guide: +```bash +cat ~/.openclaw/skills/ens-register/references/troubleshooting.md +``` + +Or open an issue: https://github.com/cruller-agent/ens-register-skill/issues + +## Uninstall + +```bash +rm -rf ~/.openclaw/skills/ens-register +``` + +## Updates + +To update to latest version: + +```bash +cd ~/.openclaw/skills/ens-register +git pull origin main +``` + +Or re-download the latest .skill package. + +## Support + +- **GitHub Issues**: https://github.com/cruller-agent/ens-register-skill/issues +- **Twitter**: @cruller_donut +- **Moltbook**: @Cruller + +## Credits + +Built by **Cruller** (@cruller_donut), DonutDAO's first autonomous agent. + +Based on successful registration of `donut-agent.eth` and deployment of DonutDAO dashboard to IPFS + ENS. + +## License + +MIT - Free to use, modify, and distribute. + +--- + +**Help other agents claim their identity! 🍩⚙️** diff --git a/community-examples/ens-register/README.md b/community-examples/ens-register/README.md new file mode 100644 index 0000000..47b469e --- /dev/null +++ b/community-examples/ens-register/README.md @@ -0,0 +1,276 @@ +# ENS Registration Skill + +**Register ENS names (.eth domains) on Ethereum mainnet using Bankr's natural language interface.** + +## What This Skill Does + +- ✅ Register .eth names (commit-reveal process) +- ✅ Check name availability +- ✅ Set primary names (reverse records) on L1 and L2 +- ✅ Create and manage subdomains +- ✅ Deploy static sites to IPFS + ENS +- ✅ Set contenthash for decentralized hosting + +## Prerequisites + +1. **Bankr skill** installed and configured +2. **ETH on Ethereum mainnet** (~0.003-0.005 ETH for registration + gas) +3. **IPFS** (optional, for content deployment) + +## Quick Start + +### Install + +```bash +# Download the skill +openclaw skills install ens-register + +# Or manually +cp ens-register.skill ~/.openclaw/skills/ +cd ~/.openclaw/skills && unzip ens-register.skill +``` + +### Register Your First ENS Name + +```bash +# Check availability +cd ~/.openclaw/skills/bankr +./scripts/bankr.sh "is my-agent.eth available?" + +# Register for 1 year +./scripts/bankr.sh "register my-agent.eth for 1 year" + +# Set as primary name +./scripts/bankr.sh "set my primary ENS name to my-agent.eth on ethereum" +``` + +**Cost**: ~0.003 ETH ($6-7) for 1 year + +## Use Cases + +### Agent Identity + +Give your AI agent a human-readable identity: + +```bash +# Register name +./scripts/bankr.sh "register cruller.eth for 1 year" + +# Set as primary (your address shows as "cruller.eth" instead of "0x123...") +./scripts/bankr.sh "set my primary ENS name to cruller.eth on ethereum" +``` + +### Deploy Dashboard to ENS + +Host your agent's dashboard on IPFS + ENS: + +```bash +# 1. Build your site +npm run build + +# 2. Upload to IPFS +ipfs add -r ./build +# Returns: QmYOUR_CID + +# 3. Create subdomain +./scripts/bankr.sh "create subdomain dashboard.cruller.eth" + +# 4. Point to IPFS content +./scripts/bankr.sh "set contenthash for dashboard.cruller.eth to ipfs://QmYOUR_CID" + +# 5. Access at https://dashboard.cruller.eth.limo/ +``` + +### Multi-Chain Primary Names + +Set your ENS name on L2s for better UX: + +```bash +# Base L2 +./scripts/bankr.sh "set my primary ENS name to cruller.eth on base" + +# Arbitrum +./scripts/bankr.sh "set my primary ENS name to cruller.eth on arbitrum" +``` + +Cost: ~$0.01 per L2 + +## Features + +### Natural Language Interface + +Powered by Bankr - just describe what you want: + +```bash +# Registration +"register my-name.eth for 3 years" +"is agent-name.eth available?" +"renew my-name.eth for 2 more years" + +# Primary Names +"set my primary ENS name to my-name.eth on ethereum" +"set my primary ENS name to my-name.eth on base" + +# Subdomains +"create subdomain demo.my-name.eth" +"create subdomain api.my-name.eth" + +# Content Hosting +"set contenthash for demo.my-name.eth to ipfs://QmCID" +"update contenthash for api.my-name.eth to ipfs://QmNEW_CID" +``` + +### Automatic Commit-Reveal + +Bankr handles the two-step ENS registration process automatically: +1. Submits commit transaction +2. Waits for it to mine +3. Submits register transaction + +No manual timing required! + +### Cost-Effective + +- **1 year**: ~$6 +- **3 years**: ~$15 ($5/year) +- **5 years**: ~$25 ($5/year) ← Most cost-effective + +Gas cost is mostly fixed, so longer registrations are cheaper per year. + +## Documentation + +The skill includes comprehensive reference documentation: + +- **SKILL.md** - Quick start guide and common workflows +- **l2-setup.md** - Set primary names on Base, Arbitrum, Optimism +- **ipfs-deployment.md** - Deploy static sites to IPFS + ENS +- **contracts.md** - ENS contract addresses and technical details +- **troubleshooting.md** - Common issues and solutions + +## Real Example + +From Cruller's registration of `donut-agent.eth`: + +```bash +# 1. Check availability +./scripts/bankr.sh "is donut-agent.eth available?" +# ✅ Available! + +# 2. Register for 1 year +./scripts/bankr.sh "register donut-agent.eth for 1 year" +# Commit TX: 0xc176280a... +# Register TX: 0xb92438b8... +# ✅ Registered! + +# 3. Set primary name +./scripts/bankr.sh "set my primary ENS name to donut-agent.eth on ethereum" +# ✅ Primary name set on L1 + +# 4. Create demo subdomain +./scripts/bankr.sh "create subdomain demo.donut-agent.eth" +# ✅ Subdomain created + +# 5. Deploy dashboard to IPFS +ipfs add -r ./dashboard-build +# CID: QmNW7suCmF95hRAjUGquEZVrd26u1Y7ocoRkiTQjvc7Bg9 + +# 6. Link subdomain to IPFS +./scripts/bankr.sh "set contenthash for demo.donut-agent.eth to ipfs://QmNW7suCmF95hRAjUGquEZVrd26u1Y7ocoRkiTQjvc7Bg9" +# ✅ Contenthash set + +# 7. Access dashboard +open https://demo.donut-agent.eth.limo/ +# 🎉 Dashboard live! +``` + +**Total time**: ~5 minutes +**Total cost**: 0.002555 ETH ($6.11) + +## Why ENS? + +### For Agents + +- **Human-readable identity**: `agent.eth` > `0x608044...3a72` +- **Verifiable**: On-chain proof of identity +- **Portable**: Works across all Ethereum apps +- **Permanent**: You own it as long as you renew + +### For Hosting + +- **Censorship-resistant**: No DNS, no takedowns +- **Cost-effective**: ~$6/year vs $20+/month traditional hosting +- **No servers**: Upload to IPFS, done +- **Fast**: CDN-like via gateway network + +### For Users + +- **Send to `agent.eth`** instead of long hex address +- **See `agent.eth`** in block explorers instead of `0x123...` +- **Trust**: On-chain verification of agent identity + +## Technical Details + +### Chains Supported + +- **Ethereum mainnet**: Name registration +- **Base**: Primary name setup +- **Arbitrum**: Primary name setup +- **Optimism**: Primary name setup + +### Requirements + +- **Bankr skill** (natural language crypto operations) +- **IPFS** (optional, for content deployment) +- **OpenClaw** (orchestration framework) + +### Gas Costs + +| Operation | Gas Cost | Current (~$3k ETH) | +|-----------|----------|-------------------| +| Commit | ~50k gas | ~$0.08 | +| Register | ~250k gas | ~$0.60 | +| Set primary (L1) | ~50k gas | ~$0.08 | +| Set primary (L2) | ~50k gas | ~$0.01 | +| Set contenthash | ~100k gas | ~$0.15 | + +Registration fee: ~$5/year (fixed) + +## Troubleshooting + +### "Insufficient funds" +Need ~0.003 ETH. Bridge from Base or buy more ETH. + +### "Name not available" +Already registered. Try variations or check expiry. + +### "Content not loading" +- Verify IPFS content is pinned +- Check contenthash format: `ipfs://QmCID` +- Wait 10-15 min for gateway cache +- Try different gateway (eth.link, dweb.link) + +See [references/troubleshooting.md](references/troubleshooting.md) for comprehensive debugging. + +## Created By + +**Cruller** (@cruller_donut) +DonutDAO's first autonomous agent + +Based on successful registration of `donut-agent.eth` and deployment of DonutDAO dashboard to IPFS + ENS. + +## Resources + +- **ENS App**: https://app.ens.domains +- **ENS Docs**: https://docs.ens.domains +- **IPFS Docs**: https://docs.ipfs.tech +- **Bankr Skill**: https://github.com/bankr/bankr-skill + +## License + +MIT - Free to use, modify, and distribute + +--- + +**Built with ❤️ for the agent ecosystem** + +Help other agents claim their identity! 🍩⚙️ diff --git a/community-examples/ens-register/SKILL.md b/community-examples/ens-register/SKILL.md new file mode 100644 index 0000000..4587796 --- /dev/null +++ b/community-examples/ens-register/SKILL.md @@ -0,0 +1,192 @@ +--- +name: ens-register +description: Register ENS names on Ethereum mainnet using Bankr's natural language interface. Use when the user wants to register an ENS name (.eth domain), check ENS name availability, set up reverse records (primary name), or deploy content to ENS subdomains via IPFS. Includes complete workflow for commit-reveal registration, primary name configuration, and subdomain management. +--- + +# ENS Registration via Bankr + +Register and configure ENS names (.eth domains) on Ethereum mainnet using Bankr's natural language crypto agent. + +## Prerequisites + +- **Bankr skill** installed and configured (`~/.openclaw/skills/bankr`) +- **ETH on Ethereum mainnet** (~0.003-0.005 ETH for registration + gas) +- **Wallet configured** in Bankr + +Check balance before starting: +```bash +cd ~/.openclaw/skills/bankr && ./scripts/bankr.sh "what's my ethereum balance?" +``` + +## Quick Start + +### 1. Check Name Availability + +ENS names must be 3+ characters. Check if available: + +```bash +cd ~/.openclaw/skills/bankr && ./scripts/bankr.sh "is my-name.eth available?" +``` + +### 2. Register the Name + +Use Bankr's natural language interface: + +```bash +cd ~/.openclaw/skills/bankr && ./scripts/bankr.sh "register my-name.eth for 1 year" +``` + +**What happens:** +1. Bankr submits commit transaction (frontrun protection) +2. Waits ~1 minute for commit to be mined +3. Submits register transaction (completes registration) +4. Optionally sets reverse record (primary name) + +**Cost:** ~0.002-0.003 ETH ($5-7) for registration + gas + +### 3. Set Primary Name (Reverse Record) + +Make your address resolve to your ENS name: + +```bash +cd ~/.openclaw/skills/bankr && ./scripts/bankr.sh "set my primary ENS name to my-name.eth on ethereum" +``` + +This sets the L1 reverse record. For Base L2, see [references/l2-setup.md](references/l2-setup.md). + +## Creating Subdomains + +### Register a Subdomain + +```bash +cd ~/.openclaw/skills/bankr && ./scripts/bankr.sh "create subdomain demo.my-name.eth" +``` + +### Point Subdomain to IPFS Content + +After deploying content to IPFS: + +```bash +cd ~/.openclaw/skills/bankr && ./scripts/bankr.sh "set contenthash for demo.my-name.eth to ipfs://QmYOUR_CID_HERE" +``` + +Access via: `https://demo.my-name.eth.limo/` + +## Common Workflows + +### Deploy Static Site to ENS + +1. Build your static site (HTML/CSS/JS) +2. Upload to IPFS: `ipfs add -r ./build` +3. Get CID from output +4. Set contenthash: `./scripts/bankr.sh "set contenthash for demo.my-name.eth to ipfs://Qm..."` +5. Access at `https://demo.my-name.eth.limo/` + +See [references/ipfs-deployment.md](references/ipfs-deployment.md) for detailed IPFS workflow. + +### Update Subdomain Content + +1. Upload new version to IPFS +2. Update contenthash with new CID +3. Changes propagate within minutes + +### Agent Identity Setup + +For agents registering their identity: + +```bash +# Register name +./scripts/bankr.sh "register agent-name.eth for 1 year" + +# Set primary name (makes wallet resolve to ENS) +./scripts/bankr.sh "set my primary ENS name to agent-name.eth on ethereum" + +# Create subdomain for dashboard +./scripts/bankr.sh "create subdomain dashboard.agent-name.eth" + +# Deploy dashboard to IPFS and link +./scripts/bankr.sh "set contenthash for dashboard.agent-name.eth to ipfs://Qm..." +``` + +## Troubleshooting + +### "Insufficient funds" +- Registration costs ~0.003 ETH total +- Check balance: `./scripts/bankr.sh "what's my ethereum balance?"` +- Bridge from Base if needed + +### "Name not available" +- Name is already registered +- Try variations or check expiry on https://app.ens.domains + +### "Commit not found" +- Wait 1-2 minutes after commit before registering +- Bankr handles timing automatically + +### "Transaction reverted" +- Increase gas limit: Specify "with higher gas limit" in prompt +- Check Etherscan for detailed error + +## Costs + +- **Registration**: ~0.002 ETH/year ($5-6) +- **Gas (commit)**: ~0.00003 ETH ($0.08) +- **Gas (register)**: ~0.00026 ETH ($0.60) +- **Total**: ~0.003 ETH ($6-7) for 1 year + +Longer registrations (3-5 years) are more cost-effective. + +## Notes + +- **Commit-reveal**: ENS uses two transactions to prevent frontrunning +- **Resolver**: Automatically set to ENS Public Resolver (0xF29100983...) +- **Renewals**: Must renew before expiry (set reminder for 11 months) +- **L2 Support**: Primary names work differently on Base/Arbitrum/Optimism (see references) + +## Advanced Usage + +For advanced topics, see reference files: + +- **L2 Primary Names**: [references/l2-setup.md](references/l2-setup.md) +- **IPFS Deployment**: [references/ipfs-deployment.md](references/ipfs-deployment.md) +- **ENS Contracts**: [references/contracts.md](references/contracts.md) +- **Troubleshooting**: [references/troubleshooting.md](references/troubleshooting.md) + +## Real Example + +From Cruller's registration of `donut-agent.eth`: + +```bash +# 1. Check availability +./scripts/bankr.sh "is donut-agent.eth available?" + +# 2. Register for 1 year +./scripts/bankr.sh "register donut-agent.eth for 1 year" + +# 3. Set primary name on L1 +./scripts/bankr.sh "set my primary ENS name to donut-agent.eth on ethereum" + +# 4. Create demo subdomain +./scripts/bankr.sh "create subdomain demo.donut-agent.eth" + +# 5. Deploy dashboard to IPFS (got CID: QmNW7...) +ipfs add -r ./dashboard-build + +# 6. Link subdomain to IPFS +./scripts/bankr.sh "set contenthash for demo.donut-agent.eth to ipfs://QmNW7suCmF95hRAjUGquEZVrd26u1Y7ocoRkiTQjvc7Bg9" + +# Access: https://demo.donut-agent.eth.limo/ +``` + +**Total cost**: 0.002555 ETH (~$6.11) +**Time**: ~5 minutes + +## Why ENS? + +- **Human-readable**: `agent.eth` vs `0x608044...3a72` +- **Decentralized**: No DNS, no takedowns +- **Portable**: Works across all Ethereum apps +- **Programmable**: Subdomains, contenthash, text records +- **Agent identity**: On-chain verifiable identity for AI agents + +Perfect for agent web presence and decentralized app hosting. diff --git a/community-examples/ens-register/references/contracts.md b/community-examples/ens-register/references/contracts.md new file mode 100644 index 0000000..ac3644b --- /dev/null +++ b/community-examples/ens-register/references/contracts.md @@ -0,0 +1,204 @@ +# ENS Contract Reference + +Key ENS contracts on Ethereum mainnet and L2s. + +## Ethereum Mainnet + +### ENS Registry +``` +Address: 0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e +``` +Root registry for all .eth names. + +### ETH Registrar Controller (v3) +``` +Address: 0x59E16fcCd424Cc24e280Be16E11Bcd56fb0CE547 +``` +Handles .eth name registrations (commit-reveal process). + +**Key Functions:** +- `makeCommitment()` - Generate commitment hash +- `commit(bytes32)` - Submit commitment +- `register()` - Complete registration after commit +- `renew()` - Extend registration + +### Public Resolver +``` +Address: 0xF29100983E058B709F3D539b0c765937B804AC15 +``` +Default resolver for ENS names. Stores: +- Addresses (ETH, BTC, etc.) +- Content hashes (IPFS, Swarm, etc.) +- Text records (email, url, avatar, etc.) + +**Key Functions:** +- `setAddr()` - Set address record +- `setContenthash()` - Set IPFS/Swarm content +- `setText()` - Set text records + +### Reverse Registrar (L1) +``` +Address: 0xA2C122BE93b0074270ebeE7f6b7292C7deB45047 +``` +Handles reverse records (address → name). + +**Key Functions:** +- `setName(string)` - Set primary name for caller +- `claim(address)` - Claim reverse record + +## Base L2 + +### Reverse Registrar +``` +Address: 0x0000000000D8e504002cC26E3Ec46D81971C1664 +``` +Set primary names on Base L2. + +**Function:** +- `setName(string)` - Set primary name (e.g., "agent.eth") + +## Arbitrum + +### Reverse Registrar +``` +Address: 0x0000000000D8e504002cC26E3Ec46D81971C1664 +``` + +## Optimism + +### Reverse Registrar +``` +Address: 0x0000000000D8e504002cC26E3Ec46D81971C1664 +``` + +## Registration Flow (Commit-Reveal) + +### Why Two Transactions? + +ENS uses commit-reveal to prevent frontrunning: + +1. **Commit**: Submit hash of (name + owner + secret) +2. **Wait**: ~1 minute minimum +3. **Reveal**: Submit actual name + owner + secret + +**Attacker can't frontrun** because they don't know the name during commit phase. + +### Cost Breakdown + +**Registration (1 year):** +- Base fee: ~0.002 ETH ($5) +- Commit gas: ~0.00003 ETH ($0.08) +- Register gas: ~0.00026 ETH ($0.60) +- **Total**: ~0.003 ETH (~$6-7) + +**Renewal (per year):** +- Base fee: ~0.002 ETH ($5) +- Gas: ~0.0001 ETH ($0.25) +- **Total**: ~0.0021 ETH (~$5.25) + +### Gas Tips + +- **Commit**: 50,000 gas +- **Register**: 250,000 gas +- **Renew**: 100,000 gas +- **Set primary name**: 50,000 gas + +Use higher gas during congestion. + +## Subdomain Creation + +Subdomains are managed by the parent name owner: + +``` +Parent: agent.eth (you own this) +Subdomain: demo.agent.eth (you control this) +``` + +**Process:** +1. Call `setSubnodeOwner()` on ENS Registry +2. Point to Public Resolver +3. Set records (address, contenthash, etc.) + +Bankr handles this automatically: +```bash +./scripts/bankr.sh "create subdomain demo.agent.eth" +``` + +## Contenthash Format + +### IPFS +``` +ipfs://QmYOUR_CID_HERE +``` + +### IPNS +``` +ipns://k51qzi5uqu5d... +``` + +### Swarm +``` +bzz://HASH +``` + +Bankr accepts these formats and handles encoding automatically. + +## Reverse Records (Primary Names) + +### How It Works + +**Forward**: `agent.eth` → `0x123...` +**Reverse**: `0x123...` → `agent.eth` + +Reverse records make your address human-readable in: +- Block explorers (Etherscan, Basescan) +- Wallets (MetaMask, Rainbow) +- dApps + +### Setting Reverse Record + +**L1 (Ethereum):** +- Option 1: Set during registration (`reverseRecord=1`) +- Option 2: Call `setName()` on Reverse Registrar + +**L2 (Base, Arbitrum, etc.):** +- Must call `setName()` on L2 Reverse Registrar +- Separate transaction per L2 + +## Text Records + +Store arbitrary key-value data: + +``` +email → agent@example.com +url → https://myagent.ai +avatar → ipfs://QmAvatarHash +com.twitter → @my_agent +``` + +Set via Public Resolver: +```bash +./scripts/bankr.sh "set text record 'url' to 'https://myagent.ai' for agent.eth" +``` + +## Name Expiry + +- Names expire after registration period (1-10 years) +- 90-day grace period after expiry (only owner can renew) +- After grace period, name becomes available to public + +**Set reminder**: Renew ~30 days before expiry to avoid downtime. + +## Security Notes + +- **Owner** controls the name (can transfer, set records) +- **Controller** set during registration (ETH Registrar Controller) +- **Resolver** can be changed by owner +- **Protect your keys** - Owner key controls the name + +## Resources + +- **ENS Docs**: https://docs.ens.domains +- **ENS App**: https://app.ens.domains +- **Contract Source**: https://github.com/ensdomains/ens-contracts +- **Etherscan**: https://etherscan.io/address/0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e diff --git a/community-examples/ens-register/references/ipfs-deployment.md b/community-examples/ens-register/references/ipfs-deployment.md new file mode 100644 index 0000000..c7426ca --- /dev/null +++ b/community-examples/ens-register/references/ipfs-deployment.md @@ -0,0 +1,245 @@ +# IPFS + ENS Deployment + +Deploy static websites to IPFS and access them via ENS subdomains. + +## Overview + +**Traditional Web**: Domain → DNS → Server IP → Website +**Decentralized Web**: ENS → Contenthash → IPFS CID → Website + +**Benefits:** +- Censorship-resistant (no central server) +- No hosting costs (IPFS is peer-to-peer) +- Immutable (content-addressed) +- Fast (CDN-like via gateways) + +## Quick Workflow + +```bash +# 1. Build your static site +npm run build # or whatever builds your site + +# 2. Upload to IPFS +ipfs add -r ./build + +# Result: QmYOUR_CID_HERE + +# 3. Set ENS contenthash +cd ~/.openclaw/skills/bankr +./scripts/bankr.sh "set contenthash for demo.my-name.eth to ipfs://QmYOUR_CID_HERE" + +# 4. Access via ENS gateway +open https://demo.my-name.eth.limo/ +``` + +## IPFS Installation + +### Option 1: IPFS Desktop (Recommended) +Download from: https://docs.ipfs.tech/install/ipfs-desktop/ + +### Option 2: Command Line +```bash +# macOS +brew install ipfs + +# Linux +wget https://dist.ipfs.tech/kubo/v0.25.0/kubo_v0.25.0_linux-amd64.tar.gz +tar -xvzf kubo_v0.25.0_linux-amd64.tar.gz +cd kubo && sudo bash install.sh + +# Initialize +ipfs init +ipfs daemon +``` + +## Uploading to IPFS + +### Single File +```bash +ipfs add index.html +# Returns: added QmHash index.html +``` + +### Directory (Recommended for websites) +```bash +ipfs add -r ./build +# Returns: added QmHash build +``` + +### Pin to Keep Content Available +```bash +ipfs pin add QmYOUR_CID +``` + +**Note**: Content stays available as long as at least one IPFS node has it pinned. + +## ENS Contenthash Setup + +### Create Subdomain +```bash +./scripts/bankr.sh "create subdomain demo.my-name.eth" +``` + +### Set Contenthash +```bash +./scripts/bankr.sh "set contenthash for demo.my-name.eth to ipfs://QmYOUR_CID" +``` + +**Format**: Always use `ipfs://` prefix + +### Update Content +```bash +# Upload new version +ipfs add -r ./new-build +# Get new CID + +# Update contenthash +./scripts/bankr.sh "set contenthash for demo.my-name.eth to ipfs://QmNEW_CID" +``` + +## Accessing Your Site + +### Via ENS Gateways +- **eth.limo**: `https://demo.my-name.eth.limo/` (Recommended) +- **eth.link**: `https://demo.my-name.eth.link/` +- **dweb.link**: `https://demo.my-name.eth.dweb.link/` + +### Via IPFS Gateways (Direct) +- `https://ipfs.io/ipfs/QmYOUR_CID` +- `https://cloudflare-ipfs.com/ipfs/QmYOUR_CID` +- `https://gateway.pinata.cloud/ipfs/QmYOUR_CID` + +### Via IPFS Desktop +- `ipfs://QmYOUR_CID` (requires IPFS companion browser extension) + +## Best Practices + +### 1. Build Optimization +```bash +# Minimize file sizes +npm run build --production + +# Compress images +# Remove source maps in production +``` + +### 2. IPFS Pinning Services + +For production, use a pinning service to ensure availability: + +**Free Tier:** +- **Pinata**: 1 GB free +- **NFT.Storage**: Unlimited free (Web3.Storage) +- **Fleek**: Free hosting + CDN + +**Setup Pinata:** +```bash +# Upload via API +curl -X POST "https://api.pinata.cloud/pinning/pinFileToIPFS" \ + -H "pinata_api_key: YOUR_KEY" \ + -H "pinata_secret_api_key: YOUR_SECRET" \ + -F "file=@./build" +``` + +### 3. Content Updates + +**Immutable**: IPFS content is content-addressed (CID = hash of content) + +**To update:** +1. Upload new version (gets new CID) +2. Update ENS contenthash to new CID +3. Old version still accessible via old CID (unless unpinned) + +### 4. Cache Busting + +ENS gateways cache content. To force refresh: +- Use versioned subdomains: `v1.app.eth`, `v2.app.eth` +- Or wait ~5-10 minutes for cache to clear after contenthash update + +## Example: DonutDAO Dashboard + +Real example from Cruller's deployment: + +```bash +# Built Next.js app +cd donutdao-dashboard +npm run build +npm run export # Static export + +# Uploaded to IPFS +ipfs add -r ./out +# Got CID: QmNW7suCmF95hRAjUGquEZVrd26u1Y7ocoRkiTQjvc7Bg9 + +# Set contenthash +./scripts/bankr.sh "set contenthash for demo.donut-agent.eth to ipfs://QmNW7suCmF95hRAjUGquEZVrd26u1Y7ocoRkiTQjvc7Bg9" + +# Live at: https://demo.donut-agent.eth.limo/ +``` + +**Features:** +- Real-time DONUT supply from Base mainnet +- gDONUT staking stats +- ETH price from Coingecko +- Pure HTML/CSS/JS (Ethers.js v6) + +## Troubleshooting + +### "Content not loading" +- Check CID is correct (case-sensitive) +- Verify content is pinned to IPFS +- Try different gateway (eth.limo vs eth.link) +- Wait 5-10 min for gateway cache + +### "Contenthash not set" +- Verify transaction succeeded on Etherscan +- Check you own the subdomain +- Ensure format: `ipfs://QmCID` (not just `QmCID`) + +### "Site works on ipfs.io but not ENS gateway" +- ENS gateways have more aggressive caching +- Wait 5-10 minutes +- Clear browser cache +- Try incognito/private window + +## Advanced: IPNS (Mutable Pointers) + +IPNS provides mutable pointers to IPFS content: + +```bash +# Create IPNS name +ipfs name publish QmYOUR_CID + +# Get IPNS hash (k51...) +# Set ENS contenthash to IPNS +./scripts/bankr.sh "set contenthash for demo.my-name.eth to ipns://k51..." + +# Update content +ipfs name publish QmNEW_CID +# Same IPNS hash, new content +``` + +**Tradeoff**: IPNS resolution is slower (~2-5 seconds) + +## Cost Comparison + +**Traditional Hosting (Vercel/Netlify):** +- Free tier: Limited builds/bandwidth +- Pro: $20/month +- Enterprise: $100+/month + +**IPFS + ENS:** +- IPFS: Free (self-hosted) or $0-20/month (pinning service) +- ENS: ~$6/year domain + ~$0.50 per contenthash update +- Total: ~$10-30/year + +**Winner**: IPFS + ENS is 10-100x cheaper for static sites. + +## Why This Matters for Agents + +1. **No server maintenance** - Upload and forget +2. **Censorship-resistant** - Can't be taken down +3. **Cost-effective** - Pennies per update +4. **Verifiable** - Content hash is cryptographic proof +5. **Portable** - Works with any ENS-compatible wallet/app + +Perfect for agent dashboards, documentation, and web presence. diff --git a/community-examples/ens-register/references/l2-setup.md b/community-examples/ens-register/references/l2-setup.md new file mode 100644 index 0000000..d3da64f --- /dev/null +++ b/community-examples/ens-register/references/l2-setup.md @@ -0,0 +1,87 @@ +# L2 Primary Name Setup + +ENS primary names (reverse records) work differently on Layer 2 networks. + +## Overview + +- **L1 (Ethereum mainnet)**: Set during registration or via `setName()` +- **L2 (Base, Arbitrum, Optimism)**: Requires separate transaction on each L2 + +## Why Separate L2 Setup? + +Each L2 has its own reverse registrar contract. Setting your primary name on Ethereum mainnet does NOT automatically set it on L2s. + +## Base L2 Setup + +### Contract Address +``` +Base L2 Reverse Registrar: 0x0000000000D8e504002cC26E3Ec46D81971C1664 +``` + +### Set Primary Name on Base + +```bash +cd ~/.openclaw/skills/bankr && ./scripts/bankr.sh "set my primary ENS name to my-name.eth on base" +``` + +**Requirements:** +- ENS name already registered on L1 +- Small amount of ETH on Base for gas (~0.0001 ETH) + +**Cost**: ~$0.01-0.02 in gas + +### Verify + +Check your address on Basescan - it should show your ENS name instead of hex address. + +## Other L2s + +### Arbitrum +``` +Arbitrum Reverse Registrar: 0x0000000000D8e504002cC26E3Ec46D81971C1664 +``` + +```bash +./scripts/bankr.sh "set my primary ENS name to my-name.eth on arbitrum" +``` + +### Optimism +``` +Optimism Reverse Registrar: 0x0000000000D8e504002cC26E3Ec46D81971C1664 +``` + +```bash +./scripts/bankr.sh "set my primary ENS name to my-name.eth on optimism" +``` + +## Workflow + +1. **Register on L1** (Ethereum mainnet) - One time, costs ~$6 +2. **Set L1 primary name** - Free if done during registration +3. **Set L2 primary names** - Optional, ~$0.01 per L2 + +## Common Issues + +### "Transaction reverted on Base" +- Make sure you have ETH on Base for gas +- Verify name is registered on L1 first +- Check that you own the name + +### "Name not resolving on L2" +- Primary name may take a few minutes to propagate +- Refresh block explorer or wallet +- Verify transaction succeeded + +## Benefits + +Setting primary name on L2: +- Your address shows as `agent.eth` instead of `0x123...` on L2 explorers +- Wallets and dApps on L2 can resolve your ENS name +- Better UX for users interacting with your agent on L2 + +## Notes + +- Each L2 requires separate transaction +- L2 gas is very cheap ($0.01-0.02 total) +- You must own the L1 name first +- L2 primary names are READ from L1 records (name must be registered on L1) diff --git a/community-examples/ens-register/references/troubleshooting.md b/community-examples/ens-register/references/troubleshooting.md new file mode 100644 index 0000000..8205041 --- /dev/null +++ b/community-examples/ens-register/references/troubleshooting.md @@ -0,0 +1,325 @@ +# ENS Registration Troubleshooting + +Common issues and solutions when registering ENS names via Bankr. + +## Registration Issues + +### "Name is not available" + +**Cause**: Name is already registered + +**Solutions:** +1. Check expiry: https://app.ens.domains/NAME.eth +2. Try variations: `my-agent.eth`, `myagent.eth`, `my-agent-ai.eth` +3. Use subdomain of existing name +4. Wait for expiry (if in grace period, check back in 90 days) + +### "Insufficient funds for registration" + +**Cause**: Not enough ETH in wallet + +**Check balance:** +```bash +cd ~/.openclaw/skills/bankr && ./scripts/bankr.sh "what's my ethereum balance?" +``` + +**Minimum needed:** +- 1 year: ~0.003 ETH ($7) +- 3 years: ~0.006 ETH ($15) +- 5 years: ~0.010 ETH ($25) + +**Solutions:** +1. Bridge ETH from Base: `./scripts/bankr.sh "bridge 0.005 ETH from base to ethereum"` +2. Buy more ETH +3. Register for shorter period (1 year minimum) + +### "Commit not found" + +**Cause**: Trying to register before commit is mined + +**How commit-reveal works:** +1. Submit commit (transaction 1) +2. Wait ~1-2 minutes for it to mine +3. Submit register (transaction 2) + +**Solution:** Wait 2-3 minutes between commit and register. Bankr handles this automatically, so if you see this error, just retry. + +### "Transaction reverted" + +**Common causes:** +1. Gas limit too low +2. Name became unavailable between commit and register +3. Insufficient ETH for gas + +**Solutions:** +```bash +# Retry with higher gas limit +./scripts/bankr.sh "register my-name.eth for 1 year with higher gas limit" + +# Check if name is still available +./scripts/bankr.sh "is my-name.eth available?" + +# Check balance +./scripts/bankr.sh "what's my ethereum balance?" +``` + +## Primary Name Issues + +### "Primary name not showing on Etherscan" + +**Cause**: Reverse record not set or not propagated + +**Solutions:** +1. Verify transaction succeeded: Check Etherscan +2. Wait 5-10 minutes for indexing +3. Re-set primary name: +```bash +./scripts/bankr.sh "set my primary ENS name to my-name.eth on ethereum" +``` +4. Clear browser cache and refresh + +### "Primary name works on L1 but not L2" + +**Cause**: L2 reverse records are separate + +**Solution:** Set primary name on each L2: +```bash +# Base +./scripts/bankr.sh "set my primary ENS name to my-name.eth on base" + +# Arbitrum +./scripts/bankr.sh "set my primary ENS name to my-name.eth on arbitrum" +``` + +Requires small amount of ETH on each L2 for gas (~$0.01). + +### "Transaction reverted on Base" + +**Causes:** +1. Name not registered on L1 first +2. No ETH on Base for gas +3. Wrong network selected + +**Solutions:** +1. Verify name is registered on Ethereum mainnet first +2. Bridge some ETH to Base (~$1 worth) +3. Specify "on base" explicitly in prompt + +## Subdomain Issues + +### "Cannot create subdomain" + +**Cause**: Don't own parent name + +**Example:** +- `demo.agent.eth` requires owning `agent.eth` +- Can't create `demo.vitalik.eth` if you don't own `vitalik.eth` + +**Solution:** Only create subdomains of names you own. + +### "Subdomain not resolving" + +**Causes:** +1. Contenthash not set +2. Resolver not configured +3. Wrong IPFS CID format + +**Check:** +```bash +# Via ENS app +open https://app.ens.domains/demo.my-name.eth + +# Via resolver +./scripts/bankr.sh "what is the contenthash for demo.my-name.eth?" +``` + +**Solutions:** +1. Set contenthash: `./scripts/bankr.sh "set contenthash for demo.my-name.eth to ipfs://QmCID"` +2. Verify IPFS CID format (must start with `Qm` or `bafy`) +3. Check IPFS content is pinned and accessible + +## IPFS Contenthash Issues + +### "Content not loading via ENS gateway" + +**Causes:** +1. Content not pinned to IPFS +2. Wrong CID format +3. Gateway caching old content +4. IPFS node offline + +**Debug:** +```bash +# Test IPFS directly +curl https://ipfs.io/ipfs/QmYOUR_CID + +# Check ENS contenthash +./scripts/bankr.sh "what is the contenthash for demo.my-name.eth?" + +# Test different gateway +open https://demo.my-name.eth.link/ # Try .link instead of .limo +``` + +**Solutions:** +1. Verify content is accessible via `ipfs.io/ipfs/CID` +2. Check contenthash format: `ipfs://QmCID` (must include `ipfs://` prefix) +3. Wait 10-15 minutes for gateway cache to clear +4. Pin content to IPFS: `ipfs pin add QmCID` +5. Use pinning service (Pinata, NFT.Storage) for reliability + +### "Contenthash transaction succeeded but content not showing" + +**Cause**: Gateway caching + +**Timeline:** +- Transaction confirmed: Instant +- Contenthash updated in ENS: ~1-2 min +- Gateway cache clear: ~5-15 min + +**Solution:** Wait 15 minutes, then try: +1. Different gateway (eth.link, dweb.link) +2. Incognito/private window +3. Direct IPFS: `ipfs.io/ipfs/CID` + +## Gas & Network Issues + +### "Gas price too high" + +**Check current gas:** +- https://etherscan.io/gastracker +- https://ethgasstation.info + +**Strategies:** +1. **Wait for lower gas** (late night/weekends usually cheaper) +2. **Use lower gas price** (transaction takes longer but costs less) +3. **Register longer** (5 years costs less per year due to fixed gas costs) + +**Gas cost ranges:** +- Low congestion: $2-5 total +- Medium: $5-15 total +- High: $15-50+ total + +Registration fee (~$5) is constant, but gas varies wildly. + +### "Network error / RPC timeout" + +**Causes:** +1. RPC node down or rate-limited +2. Network congestion +3. Internet connection issues + +**Solutions:** +1. Retry in 1-2 minutes +2. Check Bankr status +3. Verify internet connection +4. Try again during off-peak hours + +## Bankr-Specific Issues + +### "Bankr not responding" + +**Check Bankr status:** +```bash +cd ~/.openclaw/skills/bankr && ./scripts/bankr.sh "what chains do you support?" +``` + +**If failing:** +1. Check API key is configured +2. Verify `~/.openclaw/skills/bankr/config.json` exists +3. See Bankr skill documentation +4. Restart OpenClaw: `openclaw gateway restart` + +### "Command not understood" + +**Common mistakes:** +- ❌ "register my-name.eth" (missing duration) +- ✅ "register my-name.eth for 1 year" + +- ❌ "set contenthash to QmCID" (missing name) +- ✅ "set contenthash for demo.my-name.eth to ipfs://QmCID" + +**Tips:** +- Always specify duration for registrations +- Always specify target name for contenthash/subdomain operations +- Use "on ethereum" or "on base" to clarify chain +- Include full ENS name with .eth suffix + +## Getting Help + +### Check Transaction Status + +All operations involve on-chain transactions. Get TX hash from Bankr output and check: + +**Ethereum mainnet:** +``` +https://etherscan.io/tx/0xYOUR_TX_HASH +``` + +**Base:** +``` +https://basescan.org/tx/0xYOUR_TX_HASH +``` + +### Verify Name Status + +Check name details: +``` +https://app.ens.domains/YOUR-NAME.eth +``` + +Shows: +- Owner address +- Expiry date +- Resolver configuration +- Records (address, contenthash, text) + +### Community Resources + +- **ENS Discord**: https://chat.ens.domains +- **ENS Forum**: https://discuss.ens.domains +- **ENS Docs**: https://docs.ens.domains +- **Bankr Support**: Contact via OpenClaw community + +## Emergency: Name Registered to Wrong Address + +**If you registered a name but don't control it:** + +1. **Check ownership:** +```bash +./scripts/bankr.sh "who owns my-name.eth?" +``` + +2. **If you own it:** Transfer to correct address: +```bash +./scripts/bankr.sh "transfer my-name.eth to 0xNEW_ADDRESS" +``` + +3. **If someone else owns it:** The name is gone. You'll need to: + - Register a different name + - Wait for expiry and try to re-register + - Contact owner to negotiate transfer + +**Prevention:** Double-check wallet address before registering! + +## Cost Optimization Tips + +1. **Register longer periods** - Gas cost is mostly fixed, so 5 years is most cost-effective +2. **Batch operations** - Register multiple names in low-gas periods +3. **Use L2 for primary names** - Base/Arbitrum gas is ~100x cheaper than L1 +4. **Monitor gas** - Set gas price alerts, register during off-peak times + +## Success Checklist + +After registration, verify: + +- [ ] Name registered (check on app.ens.domains) +- [ ] Owner is your address +- [ ] Expiry is correct (1+ years from now) +- [ ] Primary name set on L1 +- [ ] Primary name set on L2s (if needed) +- [ ] Subdomains created (if needed) +- [ ] Contenthash set (if deploying content) +- [ ] Content accessible via ENS gateway +- [ ] Set calendar reminder to renew + +If all checked, you're done! 🎉