XMBL Liquid Token

Problem Statement

XMBL Liquid TokenThis is a defi protocol that ties in with the upcoming XMBL platform for rapid app generation, p2p web services, and yield generation from staking BTC.Users deposit value into the system via BTC or any supported tokens. Supported tokens are converted to BTC and sent to the XMBL liquidity pool. When funds are sent to the pool, XMBL NFTs are minted with Token Bound Accounts (ERC-6551) based on an algorithmic bonding curve and sent to the depositor. Each deposit creates a unique NFT with its own smart contract account that can hold assets, execute transactions, and manage DeFi positions independently.Funds from the liquidity pool are rented out to earn basis points which are distributed as dividend yields to individual XMBL NFT holders via their Token Bound Accounts. Each NFT's TBA receives yields proportional to its deposit value, enabling sophisticated per-position portfolio management.We are utilizing One-Inch APIs, contracts, and workflows to enable swaps and provision liquidity for yield generation, combined with ERC-6551 Token Bound Accounts for advanced DeFi position management.Core Protocol FeaturesTrue Bonding Curve ImplementationThe XMBL protocol implements atrue linear bonding curvewhere:Token n costs n satoshis + 1% network feeToken 1 = 1 satoshi, Token 2 = 2 satoshis, Token 3 = 3 satoshis, etc.1 satoshi = 1e10 wei conversion factorEach token's price increases linearly with the token numberNetwork fee of 1% is added to each token purchaseMeta-Token SystemFor gas efficiency and large deposits, the protocol implements ameta-token system:Meta-tokens are created when a deposit can buy >1 tokenMeta-tokens have all privileges of regular tokens (TBA, yield, withdrawal, swaps)Users can mint individual tokens from meta-tokens usingmintFromMetaToken()Meta-tokens reduce gas costs for large depositsMeta-tokens are included in yield distribution proportionallyMeta-tokens can execute TBA operations and participate in swapsERC-6551 Token Bound Accounts IntegrationThis protocol leverages ERC-6551 Token Bound Accounts to provide each XMBL NFT with its own smart contract account, enabling:Individual Asset Management: Each NFT's TBA can hold ETH, tokens, and other NFTs independentlyAutonomous DeFi Operations: TBAs can interact with other DeFi protocols, execute complex strategies, and compound yields automaticallyGranular Yield Distribution: Yields are distributed directly to each NFT's TBA based on deposit valueAdvanced Portfolio Management: Users can manage multiple sophisticated positions through different NFTsCross-Position Interactions: TBAs can interact with each other for complex arbitrage and yield optimization strategiesProgrammable Positions: Each NFT position can be programmed with custom logic and automationThis creates a new paradigm where each deposit becomes a programmable, autonomous agent in the DeFi ecosystem, capable of managing its own assets and executing sophisticated strategies while maintaining proportional yield rights in the overall protocol.Project StructureBased on your project description for "XMBL-Liquid-Token" and drawing from the provided sources, here's a comprehensive folder and file scaffold structure, organized into your requested top-level directories:client(Vue.js),server(Bun), andcontracts(EVM / one-inch). This structure integrates the core functionalities of depositing tokens, converting to BTC, minting XMBL NFTs with Token Bound Accounts (ERC-6551), managing a liquidity pool for yield generation, and distributing profits to individual TBAs, all while leveraging 1inch's infrastructure.1.client/(Vue.js / Vite Frontend)This folder will house the user interface, enabling users to interact with your DeFi protocol and manage their XMBL NFT collection with Token Bound Accounts. The frontend provides sophisticated portfolio management capabilities for individual NFT positions.public/index.html: The main HTML file for your Vue.js application.src/assets/: Contains static assets like images, global CSS, and fonts.components/: Reusable Vue components for various UI elements.WalletConnect.vue: Handles connecting to EVM-compatible wallets (e.g., MetaMask).DepositForm.vue: A form for users toselect and deposit supported tokens or BTC, creating new XMBL NFTs with Token Bound Accounts based on your algorithmic bonding curve.XMBLPortfolio.vue: Displays the user'sXMBL NFT collection, individual TBA balances, deposited values, and accrued dividend yields per NFT.TransactionHistory.vue: Shows a record of user deposits, NFT creations, swaps, and yield distributions to TBAs.services/: Modules for interacting with smart contracts and potentially your Bun backend.web3Service.ts: Encapsulates logic for interacting with EVM smart contracts, ERC-6551 registries, and Token Bound Accounts (usingethers.js) to call functions likedepositon yourXMBLVault.solcontract and manage NFT operations.apiService.ts: (Optional) If your Bun server exposes specific APIs for frontend data or actions not directly on-chain.stores/: Pinia stores for state management.wallet.ts: Manages wallet connection and XMBL NFT collection data.portfolio.ts: Manages NFT portfolio data, TBA balances, and yield information.protocol.ts: Manages protocol-wide data and statistics.transactions.ts: Manages transaction history and status.views/(orpages/): Top-level components representing different application views.Home.vue: The landing page, potentially showcasing the protocol's value proposition.Dashboard.vue: The main user dashboard where they can deposit, view their NFT portfolio, and claim yields from individual TBAs.App.vue: The root component of your Vue application.main.ts: The entry point for your Vue application.package.json: Lists frontend dependencies (e.g.,vue,ethers, UI libraries,@wagmi/corefor ERC-6551 support).vite.config.ts: Vite configuration file..env: Environment variables for public API keys (e.g., 1inch API key if directly used for quotes on client-side), contract addresses, etc.2.server/(Bun Backend)This folder will contain your off-chain logic, automations, and APIs that interact with blockchain networks, ERC-6551 Token Bound Accounts, and external services like 1inch. The server manages NFT portfolio data, TBA interactions, and yield distribution to individual Token Bound Accounts.src/api/: (Optional) If you decide to build REST APIs for your frontend or other services.routes.tscontrollers.tsservices/: Core business logic and external integrations.oneInchService.ts: Integrates with the1inch Fusion SDKand1inch APIs. This service will be crucial for:Fetching quotesfor token swaps (e.g., converting any supported token to WBTC).Creating and submitting ordersvia 1inch Fusion+.bitcoinService.ts: Manages interactions with the Bitcoin network. If you utilize Hashed Timelock Contracts (HTLCs) foratomic cross-chain swaps to native Bitcoin, this service would use libraries likebitcoinjs-libto construct and broadcast Bitcoin transactions.yieldManagementService.ts: Contains the logic for the "rental" aspect. This service wouldautomate transferring BTC from your liquidity pool to yield-generating DeFi protocols(e.g., Compound, Aave) and harvesting the earned yield.blockchainMonitor.ts: Usesethers.jstolisten for specific eventsemitted from yourXMBLVault.solcontract on Ethereum (or L2s). This is vital for tracking NFT deposits, TBA creations, swap completions, and triggering subsequent actions (like BTC bridging or yield deployment).profitDistributionService.ts: Handles the calculation and distribution of dividend yields to individual XMBL NFT holders via their Token Bound Accounts based on deposit values.utils/: Helper functions and utilities.secretGenerator.ts: Generates and manages cryptographic secrets for HTLC-based swaps if implemented.app.ts: The main entry point for your Bun backend application.package.json: Lists Bun-compatible dependencies (e.g.,@1inch/fusion-sdk,ethers,dotenv,bitcoinjs-libif used)..env: Stores sensitive information like private keys, 1inch API keys (ONE_INCH_API_KEY), and RPC URLs for your blockchain nodes.3.contracts/(EVM / One-Inch Smart Contracts with ERC-6551 Integration)This folder will contain all your Solidity smart contracts and their associated development tools and configurations, primarily built for EVM-compatible chains and designed to integrate with 1inch protocols and ERC-6551 Token Bound Accounts.contracts/XMBLVault.sol: This is yourprimary protocol contract. It will manage:Receiving user deposits(BTC or other tokens).Creating XMBL NFTs with Token Bound Accountsfor each deposit based on youralgorithmic bonding curvelogic.Initiating 1inch swapsto convert deposited tokens to WBTC (Wrapped Bitcoin) using the 1inch Fusion+ protocol or Limit Order Protocol interfaces.Interacting with a bridge (like Wormhole) to sendWBTC to native BTCon the Bitcoin network for the liquidity pool.Managing the "liquidity pool" and interacting with yourYieldManager.solfor yield generation.Functions forprofit distributionto individual NFT Token Bound Accounts or enabling theserverto trigger it.XMBLToken.sol: AnERC-6551 compatible NFT contractthat represents users' individual positions in the XMBL liquid token system. Each NFT has an associated Token Bound Account that can hold assets, execute transactions, and manage DeFi positions independently. This NFT will be minted by theXMBLVault.solcontract.EthereumHTLC.sol: (Optional, if implementing direct HTLCs for BTC swaps) Manages the EVM side of atomic swaps by locking assets and enabling claims or refunds based on secrets and timelocks.YieldManager.sol: (Optional, if yield management is handled on-chain) A contract responsible fordeploying WBTC to yield protocols(e.g., Compound V3) and harvesting yield for distribution to individual NFT Token Bound Accounts.interfaces/: Solidity interfaces for external protocols you interact with.I1inchFusion.sol: Interface for 1inch Fusion+ smart contract interactions.ILimitOrderProtocol.sol: If your on-chain logic directly interacts with the 1inch Limit Order Protocol contract.IWormholeBridge.sol: If using Wormhole for bridging WBTC to native BTC.libraries/: Any reusable Solidity libraries.OneInchHelper.sol: (Optional) Helper functions for 1inch-related calculations or order creation.scripts/: Hardhat scripts for common development tasks.deploy.js: Script todeploy all your smart contractsto a testnet (e.g., Sepolia) or mainnet, including ERC-6551 registry and TBA implementation contracts.test/: Hardhat tests for your smart contracts.XMBLVault.test.js: Comprehensive tests for yourXMBLVault.sol's functionality, including deposits, NFT creation with TBAs, 1inch swap calls, and profit distribution logic to individual Token Bound Accounts.XMBLToken.test.js: Tests for the ERC-6551 NFT contract, including TBA creation, management, and yield distribution.hardhat.config.js: Hardhat configuration file, defining networks (e.g.,sepolia,mainnet), Solidity compiler settings, and external contract addresses including ERC-6551 registry.package.json: Lists development dependencies (e.g.,hardhat,@openzeppelin/contracts,@1inch/limit-order-protocol-contract,ethers,chai)..env: Stores sensitive information for contract deployment and testing (e.g.,PRIVATE_KEY,SEPOLIA_RPC_URL).

Solution

XMBL Liquid Token - Integration PlanOverviewThis document provides the comprehensive integration plan for the XMBL Liquid Token project, coordinating development across smart contracts, server, and client sections. Each section has extensive test scaffolding already created based on source code comments, enabling Test-Driven Development (TDD).Project ArchitectureSmart Contracts(Solidity/Hardhat): Core protocol logic, ERC-6551 NFTs, DeFi integrationsServer(Bun/TypeScript): Backend services, Bitcoin integration, API endpointsClient(Vue.js/TypeScript): Frontend interface, wallet integration, user experienceIntegration Order (Based on Dependencies)Phase 1: Foundation Layer (Parallel Development)Timeline: Steps 1-4 in each section (can be done simultaneously)Smart Contracts Foundation[ ]Contracts Steps 1-4: Mock contracts → ERC-6551 infrastructure → XMBLToken → YieldManager[ ]Key Deliverable: Basic NFT minting with Token Bound Accounts working[ ]Tests to Pass: ERC-6551 and XMBLToken test suitesServer Foundation[ ]Server Steps 1-4: Environment setup → App structure → Bitcoin service → 1inch service[ ]Key Deliverable: Core services operational with external API integrations[ ]Tests to Pass: bitcoinService.test.ts and oneInchService.test.tsClient Foundation[ ]Client Steps 1-3: Environment → Services → Stores[ ]Key Deliverable: Web3 service and state management ready[ ]Tests to Pass: Service and store test suitesPhase 2: Core Protocol Implementation (Sequential Dependencies)Timeline: Complete contracts before server/client integrationSmart Contracts Core[ ]Contracts Step 5: Implement XMBLVault.sol (main protocol contract)[ ]Critical Dependency: All other sections depend on this working[ ]Integration Point: Vault contract must be deployable and functional[ ]Tests to Pass: XMBLVault.test.js (686 lines - most comprehensive)Server Integration Layer[ ]Server Steps 5-6: Blockchain monitor → Yield management[ ]Dependency: Requires deployed contracts from Phase 2[ ]Integration Point: Server must connect to deployed contracts[ ]Tests to Pass: blockchainMonitor and yieldManagement testsClient Core Components[ ]Client Steps 4-6: WalletConnect → DepositForm → Portfolio[ ]Dependency: Requires contract ABIs and deployed addresses[ ]Integration Point: Frontend must interact with live contracts[ ]Tests to Pass: Core component test suitesPhase 3: Advanced Features (Cross-Chain & External Integrations)Timeline: Build advanced features requiring all foundation componentsCross-Chain Infrastructure[ ]Contracts Steps 6-9: HTLC → OneInch → 1inch interfaces → Wormhole[ ]Server Step 7: Profit distribution service[ ]Integration Point: Cross-chain Bitcoin ↔ Ethereum functionality[ ]Tests to Pass: HTLC, interface, and profit distribution testsAPI and User Interface[ ]Server Step 8: API controllers and routes[ ]Client Steps 7-8: Transaction history → Application views[ ]Integration Point: Frontend consumes backend APIs[ ]Tests to Pass: API endpoint and view component testsPhase 4: Production Integration (Full System Testing)Timeline: Complete system integration and deployment preparationFinal Implementation[ ]All Sections Step 9: Utilities, configuration, final features[ ]All Sections Step 10: Integration testing, production readinessSystem Integration Testing[ ]Cross-Section Integration: Verify all components work together[ ]End-to-End Testing: Complete user workflows from frontend to blockchain[ ]Performance Testing: Load testing, gas optimization, response timesCritical Integration Points1. Contract ↔ Server Integration// Server must connect to deployed contracts const vaultContract = new ethers.Contract( VAULT_ADDRESS, VAULT_ABI, provider )[ ] Contract addresses configuration[ ] ABI synchronization[ ] Event monitoring setup[ ] Transaction submission coordination2. Server ↔ Client Integration// Client consumes server APIs const apiClient = new ApiService({ baseURL: SERVER_URL, timeout: 10000 })[ ] API endpoint coordination[ ] Authentication flow[ ] Real-time event streaming[ ] Error handling consistency3. Client ↔ Contract Integration// Direct client-contract interaction const web3Service = new Web3Service({ contracts: CONTRACT_CONFIG, provider: walletProvider })[ ] Contract ABI imports[ ] Transaction signing flow[ ] Event subscription[ ] Gas estimation integrationConfiguration ManagementDevelopment Environment# Contracts cd contracts && npm run deploy:local # Server cd server && bun run dev # Client cd client && bun run devEnvironment Variables Coordination[ ]Contracts: Network configs, gas settings[ ]Server: RPC URLs, API keys, database connections[ ]Client: Contract addresses, API endpoints, wallet configsTesting Integration StrategyTest Execution OrderUnit Tests: Each section independentlyIntegration Tests: Cross-section communicationEnd-to-End Tests: Complete user workflowsShared Test Data[ ] Contract addresses after deployment[ ] Test account private keys/addresses[ ] Mock API responses for consistency[ ] Test Bitcoin HTLC parametersContinuous Integration# Run all tests across sections npm run test:all # Integration test suite npm run test:integration # End-to-end test suite npm run test:e2eProgress Tracking CoordinationDaily Progress Updates[ ] Each section updates their progress.md after step completion[ ] Cross-reference dependencies before proceeding[ ] Identify and resolve integration blockers immediatelyIntegration Checkpoints[ ]Checkpoint 1: Foundation complete (all sections steps 1-4)[ ]Checkpoint 2: Core protocol working (contracts step 5, basic server/client)[ ]Checkpoint 3: Advanced features functional (cross-chain, APIs, full UI)[ ]Checkpoint 4: Production ready (all tests passing, deployment ready)Risk MitigationDependency Risks[ ]Contract deployment issues: Have backup deployment strategy[ ]External API failures: Implement fallback mechanisms[ ]Integration timing: Maintain parallel development where possibleQuality Assurance[ ]Test Coverage: Aim for 100% since tests are pre-written[ ]Code Review: Cross-section review for integration points[ ]Performance: Monitor gas costs, API response times, UI responsivenessSuccess CriteriaTechnical Completion[ ] All test suites passing across all three sections[ ] Complete user flow: Connect wallet → Deposit → Mint NFT → Earn yield → Claim rewards[ ] Cross-chain functionality: Bitcoin HTLC operations working[ ] Real-time features: Live updates, transaction monitoringProduction Readiness[ ] Deployed on testnet with verified contracts[ ] Server deployed with health checks and monitoring[ ] Frontend deployed with proper SEO and analytics[ ] Documentation complete for all APIs and contractsFinal Integration Command# After all sections complete their individual steps npm run deploy:integration # Deploy all components to testnet npm run test:full-stack # Run complete integration test suite npm run verify:production # Verify production readinessThis coordinated approach ensures systematic development while maintaining the test-driven methodology across all three sections of the XMBL Liquid Token project.