267 lines
8.9 KiB
Markdown
267 lines
8.9 KiB
Markdown
# Research Index: Balancer V3 & Gyroscope Integration
|
|
|
|
**Complete research package for deploying your bonding curve as a Balancer V3 custom pool**
|
|
|
|
---
|
|
|
|
## 📋 Documents Created
|
|
|
|
| File | Purpose | Length | Read Time |
|
|
|------|---------|--------|-----------|
|
|
| **[RESEARCH_SUMMARY.md](./RESEARCH_SUMMARY.md)** | Executive summary + quick reference | 3,000 words | 15 min |
|
|
| **[BALANCER_V3_GYROSCOPE_RESEARCH.md](./BALANCER_V3_GYROSCOPE_RESEARCH.md)** | Comprehensive technical analysis | 20,000+ words | 1-2 hours |
|
|
| **[INTEGRATION_REFERENCE.md](./INTEGRATION_REFERENCE.md)** | Implementation guide + code snippets | 8,000 words | 45 min |
|
|
| **[GYROSCOPE_MAPPING.md](./GYROSCOPE_MAPPING.md)** | Your system vs. production Gyroscope | 6,000 words | 30 min |
|
|
|
|
**Total**: 37,000+ words of analysis spanning:
|
|
- Architecture (Balancer V3 vault design)
|
|
- Math (E-CLP, P-AMM, reserve tranching)
|
|
- Integration (contract interfaces, deployment)
|
|
- Risk (mitigations, audits, rollout strategy)
|
|
|
|
---
|
|
|
|
## 🎯 Quick Start (Pick Your Role)
|
|
|
|
### CTO / Architect
|
|
1. ⏱️ **5 min**: Skim RESEARCH_SUMMARY.md "Key Findings"
|
|
2. ⏱️ **30 min**: Read BALANCER_V3_GYROSCOPE_RESEARCH.md sections 1-3 (architecture)
|
|
3. ⏱️ **15 min**: Review GYROSCOPE_MAPPING.md "Risk Analysis"
|
|
4. ⏱️ **Then**: Plan Solidity task breakdown
|
|
|
|
→ **Total time**: 50 minutes
|
|
|
|
---
|
|
|
|
### Solidity Developer
|
|
1. ⏱️ **10 min**: Read RESEARCH_SUMMARY.md "Python Primitives" section
|
|
2. ⏱️ **30 min**: Study INTEGRATION_REFERENCE.md Part 1-3 (addresses, translation patterns, hooks)
|
|
3. ⏱️ **20 min**: Copy code snippets (Parts 4-5) into Foundry project
|
|
4. ⏱️ **Then**: Start implementation with test scaffold
|
|
|
|
→ **Total time**: 60 minutes
|
|
|
|
---
|
|
|
|
### Security / Audit Lead
|
|
1. ⏱️ **20 min**: Read BALANCER_V3_GYROSCOPE_RESEARCH.md section 10 (risk assessment)
|
|
2. ⏱️ **20 min**: Review GYROSCOPE_MAPPING.md Part 7-8 (risk analysis)
|
|
3. ⏱️ **15 min**: Check INTEGRATION_REFERENCE.md Part 6 (deployment checklist)
|
|
4. ⏱️ **Then**: Create audit scope and timeline
|
|
|
|
→ **Total time**: 55 minutes
|
|
|
|
---
|
|
|
|
### Product / Community Manager
|
|
1. ⏱️ **10 min**: Read RESEARCH_SUMMARY.md findings
|
|
2. ⏱️ **20 min**: Skim BALANCER_V3_GYROSCOPE_RESEARCH.md section 5 (community relevance)
|
|
3. ⏱️ **15 min**: Review GYROSCOPE_MAPPING.md Part 5 (feature parity)
|
|
4. ⏱️ **Then**: Plan marketing & community rollout
|
|
|
|
→ **Total time**: 45 minutes
|
|
|
|
---
|
|
|
|
## 🗺️ Document Navigation
|
|
|
|
### Finding Specific Topics
|
|
|
|
**"How do I build a custom Balancer V3 pool?"**
|
|
→ BALANCER_V3_GYROSCOPE_RESEARCH.md section 3
|
|
|
|
**"What interfaces do I need to implement?"**
|
|
→ INTEGRATION_REFERENCE.md Part 1 (contract addresses) + Part 2-3 (code)
|
|
|
|
**"How does my Python code map to Solidity?"**
|
|
→ INTEGRATION_REFERENCE.md Part 2 (translation guide)
|
|
|
|
**"What are the risks?"**
|
|
→ GYROSCOPE_MAPPING.md Part 8 (risk analysis)
|
|
|
|
**"What's the deployment timeline?"**
|
|
→ RESEARCH_SUMMARY.md "Finding 4" or BALANCER_V3_GYROSCOPE_RESEARCH.md section 12
|
|
|
|
**"How does my system compare to Gyroscope?"**
|
|
→ GYROSCOPE_MAPPING.md (entire document)
|
|
|
|
**"What test networks should I use?"**
|
|
→ BALANCER_V3_GYROSCOPE_RESEARCH.md section 5 (deployment networks)
|
|
|
|
**"Can I use existing Balancer pools for my treasury?"**
|
|
→ BALANCER_V3_GYROSCOPE_RESEARCH.md section 7.1 (weighted pool example)
|
|
|
|
---
|
|
|
|
## 📊 Your Python Code Reference
|
|
|
|
### E-CLP (Elliptical Concentrated Liquidity Pool)
|
|
**File**: `/home/jeffe/Github/myco-bonding-curve/src/primitives/elliptical_clp.py`
|
|
|
|
**Key insight**: Production-grade math. Direct translation to Solidity needed.
|
|
|
|
**Balancer V3 mapping**: `IBasePool` interface (onSwap, computeInvariant, computeBalance)
|
|
|
|
**Effort**: 2 weeks (experienced Solidity dev)
|
|
|
|
---
|
|
|
|
### P-AMM (Primary AMM / Redemption Curve)
|
|
**File**: `/home/jeffe/Github/myco-bonding-curve/src/primitives/redemption_curve.py`
|
|
|
|
**Key insight**: Pricing logic for bonding curves with circuit breakers. Works as Hooks pattern.
|
|
|
|
**Balancer V3 mapping**: `IHooks` interface (beforeSwap, afterSwap)
|
|
|
|
**Effort**: 1 week
|
|
|
|
---
|
|
|
|
### Reserve Tranching (Multi-Vault Reserve Management)
|
|
**File**: `/home/jeffe/Github/myco-bonding-curve/src/primitives/reserve_tranching.py`
|
|
|
|
**Key insight**: Safety checks for multi-vault reserves. Works as validator hooks.
|
|
|
|
**Balancer V3 mapping**: `IHooks` interface (beforeAddLiquidity, beforeRemoveLiquidity)
|
|
|
|
**Effort**: 1.5 weeks
|
|
|
|
---
|
|
|
|
## ⏱️ Implementation Timeline
|
|
|
|
| Phase | Duration | What | Status |
|
|
|-------|----------|------|--------|
|
|
| **1. Proof of Concept** | Weeks 1-2 | E-CLP to Solidity stub | 📋 Planned |
|
|
| **2. Custom Pool Integration** | Weeks 3-4 | Factory, IBasePool impl, tests | 📋 Planned |
|
|
| **3. Hooks Integration** | Weeks 5-6 | P-AMM hook, tranching validator | 📋 Planned |
|
|
| **4. Audit Prep** | Weeks 7-8 | Docs, threat model, code audit | 📋 Planned |
|
|
| **5. Security Audit** | Weeks 9-10 | External firm (Trail of Bits style) | 📋 Planned |
|
|
| **6. Testnet** | Weeks 11-12 | Launch + community feedback | 📋 Planned |
|
|
| **7. Mainnet** | Weeks 13-16 | Phased rollout (cap increases) | 📋 Planned |
|
|
|
|
**Total**: 16 weeks with 2-4 person team
|
|
**Critical Path**: Solidity dev → All other tasks depend on E-CLP completion
|
|
|
|
---
|
|
|
|
## ✅ Completion Checklist
|
|
|
|
- [x] E-CLP mathematics documented
|
|
- [x] P-AMM pricing logic documented
|
|
- [x] Reserve tranching documented
|
|
- [x] Balancer V3 architecture explained
|
|
- [x] Custom pool implementation guide created
|
|
- [x] Hooks system explained
|
|
- [x] Contract interface mapping provided
|
|
- [x] Code examples (Solidity) provided
|
|
- [x] Test strategies documented
|
|
- [x] Deployment networks identified
|
|
- [x] Risk assessment completed
|
|
- [x] Timeline estimated
|
|
- [x] Gyroscope comparison created
|
|
- [ ] Solidity implementation (your work starts here)
|
|
- [ ] Security audit (external)
|
|
- [ ] Testnet launch
|
|
- [ ] Mainnet deployment
|
|
|
|
---
|
|
|
|
## 🔗 External Resources
|
|
|
|
### Official Docs (Bookmark These)
|
|
- [Balancer V3 Docs](https://docs.balancer.fi/) — Architecture, examples
|
|
- [Balancer V3 GitHub](https://github.com/balancer/balancer-v3-monorepo) — Source code
|
|
- [Gyroscope Docs](https://docs.gyro.finance/) — Reference implementation
|
|
- [Gyroscope GitHub](https://github.com/gyrostable/) — Source code
|
|
|
|
### Key Contracts (Reference)
|
|
- `GyroECLPPool.sol` — E-CLP pool (Balancer V3)
|
|
- `PrimaryAMMV1.sol` — P-AMM (Gyroscope)
|
|
- `ReserveManager.sol` — Reserve system (Gyroscope)
|
|
- `BasePoolFactory.sol` — Factory pattern (Balancer)
|
|
|
|
### Tools You'll Need
|
|
- **Foundry** — Smart contract testing
|
|
- **PRBMath** — Fixed-point arithmetic library
|
|
- **Solidity ^0.8.24** — Latest version (EIP-1153 support)
|
|
|
|
---
|
|
|
|
## 💬 Questions?
|
|
|
|
| Question | Answer Location |
|
|
|----------|-----------------|
|
|
| "What's different from Gyroscope?" | GYROSCOPE_MAPPING.md section 2 |
|
|
| "How do I start coding?" | INTEGRATION_REFERENCE.md Part 2 |
|
|
| "What are the risks?" | BALANCER_V3_GYROSCOPE_RESEARCH.md section 10 |
|
|
| "What networks should I target?" | BALANCER_V3_GYROSCOPE_RESEARCH.md section 5 |
|
|
| "How long will this take?" | RESEARCH_SUMMARY.md Finding 4 |
|
|
| "Do I need an audit?" | GYROSCOPE_MAPPING.md Part 8 |
|
|
| "Can my community use this?" | BALANCER_V3_GYROSCOPE_RESEARCH.md section 5 |
|
|
| "What's the contract interface?" | INTEGRATION_REFERENCE.md Part 1-3 |
|
|
|
|
---
|
|
|
|
## 📝 How to Read (Recommended Order)
|
|
|
|
### For First-Time Overview
|
|
1. RESEARCH_SUMMARY.md (15 min)
|
|
2. BALANCER_V3_GYROSCOPE_RESEARCH.md sections 1-2 (30 min)
|
|
3. GYROSCOPE_MAPPING.md (20 min)
|
|
|
|
→ You'll understand the full picture
|
|
|
|
### For Implementation Start
|
|
1. INTEGRATION_REFERENCE.md Part 1-2 (30 min)
|
|
2. Copy code snippets (Part 3-5) into Foundry project
|
|
3. Run tests from Part 5 as template
|
|
4. Reference BALANCER_V3_GYROSCOPE_RESEARCH.md as needed
|
|
|
|
→ You'll be ready to code
|
|
|
|
### For Audit/Security Review
|
|
1. BALANCER_V3_GYROSCOPE_RESEARCH.md section 10 (risk assessment)
|
|
2. GYROSCOPE_MAPPING.md sections 7-8 (risk analysis + audit checklist)
|
|
3. INTEGRATION_REFERENCE.md Part 6 (deployment checklist)
|
|
|
|
→ You'll have audit scope
|
|
|
|
---
|
|
|
|
## 🚀 Next Steps (Right Now)
|
|
|
|
1. **Pick your role above** → Read the recommended documents (45-60 min)
|
|
2. **Share with team** → Each person reads their role section
|
|
3. **Plan implementation** → Use timeline as template
|
|
4. **Start Solidity** → Week 1 with code snippets from INTEGRATION_REFERENCE.md
|
|
5. **Monitor progress** → Check against phase checkpoints
|
|
|
|
---
|
|
|
|
## 📦 Deliverables Summary
|
|
|
|
What you now have:
|
|
- ✅ Complete architecture understanding
|
|
- ✅ Python → Solidity translation guide
|
|
- ✅ Code snippets ready to implement
|
|
- ✅ Test framework template
|
|
- ✅ Risk assessment + mitigations
|
|
- ✅ 16-week implementation timeline
|
|
- ✅ Deployment checklist
|
|
- ✅ Audit scope guidance
|
|
|
|
What you need to do:
|
|
- 📋 Write Solidity (weeks 1-6)
|
|
- 📋 Run tests (weeks 1-6)
|
|
- 📋 Security audit (weeks 7-10)
|
|
- 📋 Testnet + mainnet (weeks 11-16)
|
|
|
|
---
|
|
|
|
**Created**: April 3, 2026
|
|
**Status**: Ready for implementation
|
|
**Questions**: Review the document map above
|
|
|
|
Good luck! 🎯
|