@lagoon-protocol/lagoon-mcp 0.6.0 → 0.7.0

package/README.md

@@ -1,5 +1,10 @@
 # Lagoon MCP Server
 
+[![npm](https://img.shields.io/npm/v/@lagoon-protocol/lagoon-mcp)](https://www.npmjs.com/package/@lagoon-protocol/lagoon-mcp)
+[![CI](https://github.com/hopperlabsxyz/lagoon-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/hopperlabsxyz/lagoon-mcp/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/@lagoon-protocol/lagoon-mcp)](./LICENSE)
+[![node](https://img.shields.io/node/v/@lagoon-protocol/lagoon-mcp)](https://nodejs.org)
+
 Model Context Protocol (MCP) server providing Claude Code with conversational access to Lagoon DeFi vault analytics.
 
 ## Overview
@@ -24,14 +29,14 @@ Lagoon MCP enables natural language queries about DeFi vaults, user portfolios,
 - Claude Desktop app
 - Access to Lagoon backend GraphQL endpoint
 
-### Installation (will be updated after publishing)
+### Installation
 
 ```bash
 # Install globally
-npm install -g @hopperlabsxyz/lagoon-mcp
+npm install -g @lagoon-protocol/lagoon-mcp
 
 # Or install locally
-npm install @hopperlabsxyz/lagoon-mcp
+npm install @lagoon-protocol/lagoon-mcp
 ```
 
 ### Configuration
@@ -43,8 +48,19 @@ npm install @hopperlabsxyz/lagoon-mcp
 | **Claude Desktop** | ✅ Available Now | JSON | [↓ See below](#claude-desktop) |
 | **Claude Code (CLI)** | ✅ Available Now | JSON | [↓ See below](#claude-code-cli) |
 | **OpenAI Agents SDK** | ✅ Available Now | YAML | [↓ See below](#openai-agents-sdk) |
-| **ChatGPT Desktop** | ⏳ Coming Soon | JSON (expected) | [↓ See below](#chatgpt-desktop) |
-| **Grok** | ❌ Not Supported | N/A | No native MCP support |
+
+> The server uses the standard MCP stdio transport, so **any MCP-compatible client** (Cursor, Cline, and others) works with no code changes — only the config format differs.
+
+#### Environment Variables
+
+All configuration is supplied through environment variables (validated at startup). See [.env.example](./.env.example).
+
+| Variable | Required | Default | Purpose |
+|----------|----------|---------|---------|
+| `LAGOON_GRAPHQL_URL` | Recommended | `http://localhost:3001/query` | Lagoon backend GraphQL endpoint (use `https://api.lagoon.finance/query` for production) |
+| `NODE_ENV` | No | `development` | Runtime mode: `development` / `production` / `test` |
+| `CACHE_TTL` | No | `600` | Default cache TTL, in seconds |
+| `CACHE_MAX_KEYS` | No | `1000` | Maximum number of cache entries |
 
 ---
 
@@ -76,7 +92,7 @@ Add to your Claude Desktop config file:
       "command": "node",
       "args": ["/path/to/lagoon-mcp/dist/index.js"],
       "env": {
-        "LAGOON_GRAPHQL_URL": "http://localhost:3000/query"
+        "LAGOON_GRAPHQL_URL": "http://localhost:3001/query"
       }
     }
   }
@@ -95,7 +111,7 @@ Claude Code CLI uses a project-scoped configuration system. You can configure MC
 
 Edit your `~/.claude.json` file and add lagoon-mcp to your project:
 
-**For production use** (after `npm install -g @hopperlabsxyz/lagoon-mcp`):
+**For production use** (after `npm install -g @lagoon-protocol/lagoon-mcp`):
 
 ```json
 {
@@ -127,7 +143,7 @@ Edit your `~/.claude.json` file and add lagoon-mcp to your project:
           "command": "node",
           "args": ["/absolute/path/to/lagoon-mcp/dist/index.js"],
           "env": {
-            "LAGOON_GRAPHQL_URL": "http://localhost:3000/query"
+            "LAGOON_GRAPHQL_URL": "http://localhost:3001/query"
           }
         }
       }
@@ -207,33 +223,9 @@ const lagoonServer = new MCPServerStdio({
 
 ---
 
-#### ChatGPT Desktop
-
-**Status**: MCP support for ChatGPT Desktop is currently in development and expected "in the coming months" per OpenAI.
-
-**Availability**:
-- ⏳ Desktop app with MCP: Not yet released
-- ⏳ Enterprise/Team: Limited beta access only
-- ❌ Individual ChatGPT Plus: Not available yet
-
-**Expected Configuration** (once available):
-
-Configuration file location will likely follow a similar pattern to Claude Desktop (exact location TBD).
-
-```json
-{
-  "mcpServers": {
-    "lagoon": {
-      "command": "lagoon-mcp",
-      "env": {
-        "LAGOON_GRAPHQL_URL": "https://api.lagoon.finance/query"
-      }
-    }
-  }
-}
-```
+#### Other MCP clients
 
-**Technical Note**: The lagoon-mcp server is already compatible with ChatGPT's MCP implementation (uses standard MCP protocol and stdio transport). No code changes will be needed once ChatGPT Desktop launches with MCP support
+The server speaks the standard MCP protocol over stdio transport, so any MCP-compatible client works — including new clients as they add MCP support. Only the configuration format differs from the examples above; point the client at the `lagoon-mcp` command and set `LAGOON_GRAPHQL_URL`.
 
 ### Usage
 
@@ -291,18 +283,29 @@ Complete tool documentation available in [docs/tools/](./docs/tools/).
 
 | Tool | Description | Documentation |
 |------|-------------|---------------|
+| **discover_tools** | Search and discover available tools by category or keyword | — |
 | **query_graphql** | Execute raw GraphQL queries for advanced use cases | [→ Details](./docs/tools/query-graphql.md) |
 | **get_vault_data** | Get comprehensive vault information by address and chain | [→ Details](./docs/tools/get-vault-data.md) |
 | **get_user_portfolio** | Aggregate user holdings across all supported chains | [→ Details](./docs/tools/user-portfolio.md) |
 | **search_vaults** | Search and filter vaults with 20+ advanced criteria | [→ Details](./docs/tools/search-vaults.md) |
 | **get_vault_performance** | Historical metrics and performance analysis | [→ Details](./docs/tools/vault-performance.md) |
 | **get_transactions** | Query vault transaction history with flexible filtering | [→ Details](./docs/tools/get-transactions.md) |
-| **compare_vaults** | Side-by-side vault comparison with 12-factor risk analysis and rankings | [→ Details](./docs/tools/compare-vaults.md) |
-| **optimize_portfolio** | Modern Portfolio Theory optimization with yield sustainability warnings | [→ Details](./docs/tools/optimize-portfolio.md) |
+| **compare_vaults** | Side-by-side vault comparison with normalized metrics and rankings (2–20 vaults, cross-chain) | [→ Details](./docs/tools/compare-vaults.md) |
 | **get_price_history** | Historical share price data with OHLCV time-series | [→ Details](./docs/tools/price-history.md) |
-| **export_data** | Export vault data in CSV/JSON format | [→ Details](./docs/tools/export-data.md) |
+| **export_data** | Export vault data, transactions, price history, or performance in CSV/JSON format | [→ Details](./docs/tools/export-data.md) |
 | **analyze_risk** | Multi-factor risk analysis with comprehensive scoring | [→ Details](./docs/tools/analyze-risk.md) |
+| **analyze_risks** | Batch risk analysis for 2–20 vaults in a single call (cross-chain) | — |
 | **predict_yield** | ML-based yield forecasting with confidence intervals | [→ Details](./docs/tools/predict-yield.md) |
+| **optimize_portfolio** | Modern Portfolio Theory optimization with yield sustainability warnings | [→ Details](./docs/tools/optimize-portfolio.md) |
+| **simulate_vault** | Simulate vault behavior under different parameters for scenario analysis | [→ Details](./docs/tools/simulate-vault.md) |
+| **get_vault_composition** | Typed DeFi protocol composition (Vault.composition) with HHI diversification scoring. Chain-aware (requires chainId). | — |
+| **get_global_tvl** | Live total value locked across all Lagoon vaults & chains (USD) | — |
+| **get_indexing_status** | Last indexed block per chain — call BEFORE analytics to detect stale data | — |
+| **list_chains** | Lagoon-supported chains with chainId, factory address, wrapped native token | — |
+| **list_curators** | Curator directory (name, id, description, website) | — |
+| **get_curator** | Single curator lookup by id | — |
+| **get_asset** | ERC20 asset metadata + current USD price | — |
+| **get_historical_state** | Vault state at a specific Unix timestamp (price-per-share, fees, totalAssets, roles, guardrails) | — |
 
 **See also**: [Tool Selection Guide](./docs/tools/README.md#tool-selection-guide) | [Common Workflows](./docs/tools/README.md#common-workflows)
 
@@ -379,12 +382,22 @@ Skills are procedural knowledge modules that enhance how Claude uses MCP tools.
 
 ### Available Skills
 
+**Customer-facing**
+
 | Skill | Purpose | Audience |
 |-------|---------|----------|
 | `lagoon-onboarding` | Guide new users to first vault selection | New Users |
 | `lagoon-portfolio-review` | Quarterly portfolio health checks | Existing Users |
 | `lagoon-risk-expert` | Comprehensive risk evaluation | Advanced Users |
 
+**Internal team**
+
+| Skill | Purpose | Audience |
+|-------|---------|----------|
+| `lagoon-protocol-health` | Daily/weekly KPI monitoring | Operations |
+| `lagoon-curator-evaluation` | Partnership assessment with scoring | Business Development |
+| `lagoon-customer-support` | Support response templates | Support Team |
+
 ### Using Skills
 
 #### With Claude Desktop
@@ -413,7 +426,7 @@ const { systemPrompt, detectedSkill, tokensAdded } = buildSkillAwarePrompt(
 );
 
 const response = await claude.messages.create({
-  model: 'claude-sonnet-4-20250514',
+  model: 'claude-sonnet-4-6',
   system: systemPrompt,
   tools: mcpTools,
   messages: [{ role: 'user', content: userMessage }]
@@ -424,7 +437,7 @@ const response = await claude.messages.create({
 
 ## Development
 
-For development setup, testing, and contributing guidelines, see [DEVELOPMENT.md](./docs/DEVELOPMENT.md).
+For gotchas, conventions, testing, and how to add a tool, see [docs/agent-notes.md](./docs/agent-notes.md) (the developer reference, also imported by [CLAUDE.md](./CLAUDE.md)).
 
 ### Quick Start
 
@@ -452,16 +465,21 @@ npm test
 ```
 lagoon-mcp/
 ├── docs/
-│   ├── DEVELOPMENT.md          # Development guide
+│   ├── agent-notes.md          # Developer reference (gotchas, conventions, add-a-tool)
 │   └── tools/                  # Individual tool documentation
 ├── skills/                     # Claude Skills for enhanced interactions
 ├── src/
-│   ├── tools/                  # Tool implementations
+│   ├── tools/                  # Tool implementations + registry.ts
+│   ├── services/               # Business-logic services (e.g. RiskService)
 │   ├── resources/              # MCP resources
 │   ├── prompts/                # MCP prompts
 │   ├── skills/                 # Skills TypeScript API
-│   ├── graphql/                # GraphQL client and fragments
-│   ├── cache/                  # Caching layer
+│   ├── graphql/                # GraphQL client, queries, fragments
+│   ├── sdk/                    # APR, simulation, and math utilities
+│   ├── core/                   # DI container, cache adapter, invalidation
+│   ├── cache/                  # Cache TTL and key definitions
+│   ├── schemas/                # Zod config/env schemas
+│   ├── types/                  # TypeScript + generated GraphQL types
 │   └── utils/                  # Utilities
 ├── tests/                      # Test suite
 └── package.json
@@ -489,8 +507,8 @@ lagoon-mcp/
 ### Architecture Patterns
 
 **Hybrid Service Layer**:
-- **Direct GraphQL** for simple operations (12/13 tools)
-- **Service Layer** for complex multi-step operations (e.g., RiskService)
+- **Direct GraphQL** for simple operations (most tools)
+- **Service Layer** for complex multi-step operations (e.g., `RiskService` for risk analysis)
 - See [ADR-001](./docs/architecture/ADR-001-service-layer.md) for decision rationale
 
 **Dependency Injection**:
@@ -544,12 +562,14 @@ export function createExecuteAnalyzeRisk(container: ServiceContainer) {
 
 | Data Type | TTL | Rationale | Cache Tag |
 |-----------|-----|-----------|-----------|
-| Transactions | 5 min | Frequently changing | `TRANSACTION` |
 | User portfolios | 5 min | Dynamic user holdings | `PORTFOLIO` |
 | Search results | 10 min | Balance freshness/performance | `VAULT` |
+| Transactions | 15 min | Recent activity, moderately static | `TRANSACTION` |
 | Vault data | 15 min | Relatively static | `VAULT` |
+| Vault composition | 15 min | Backend caches Octav data ~6h | `VAULT` |
 | Risk analysis | 15 min | Multi-factor metrics | `RISK` |
 | Performance data | 30 min | Historical, less volatile | `PERFORMANCE` |
+| Price history | 30 min | Daily aggregates | `PERFORMANCE` |
 | Yield predictions | 60 min | ML forecasts valid longer | `PREDICTION` |
 | Schema | 24 hours | Rarely changes | `SCHEMA` |
 
@@ -621,11 +641,8 @@ Type 'unknown' is not assignable to type 'Vault'
 
 ## FAQ
 
-**Q: Does this work with ChatGPT?**  
-A: Not yet for end users. ChatGPT Desktop MCP support is "coming in the coming months" per OpenAI. Currently available for API developers via OpenAI Agents SDK (YAML config format). See the [ChatGPT Desktop section](#chatgpt-desktop) above.
-
-**Q: Does this work with Grok?**  
-A: No. xAI has not announced native MCP support for Grok, and there is no Grok desktop app with MCP capabilities. We recommend using Claude Desktop or waiting for ChatGPT Desktop MCP support.
+**Q: Which clients does this work with?**  
+A: Any MCP-compatible client. It's verified with Claude Desktop, Claude Code (CLI), and the OpenAI Agents SDK, and works with other MCP clients (e.g. Cursor, Cline) since it uses the standard stdio transport. Clients without native MCP support cannot use it until they add MCP.
 
 **Q: Do I need to modify the code for different platforms?**  
 A: No! The lagoon-mcp server is already compatible with all MCP clients (uses standard MCP protocol and stdio transport). Only configuration format differs between platforms.
@@ -643,10 +660,10 @@ A: Yes! The MCP protocol is standard. Any MCP-compatible client should work (e.g
 A: No rate limiting in MCP. Backend GraphQL API is public with no auth.
 
 **Q: Can I add custom tools?**
-A: Yes! Fork the repo, add your tool in `src/tools/`, and register in `src/tools/index.ts`.
+A: Yes! Fork the repo, add your tool in `src/tools/`, and register it in `TOOL_REGISTRY` in `src/tools/registry.ts`.
 
 **Q: How do I update to a new version?**
-A: Run `npm update -g @hopperlabsxyz/lagoon-mcp` and restart Claude Desktop.
+A: Run `npm update -g @lagoon-protocol/lagoon-mcp` and restart Claude Desktop.
 
 **Q: Does this work with all chains?**
 A: Yes! Supports all chains available in the Lagoon backend (12+ networks).
@@ -659,7 +676,8 @@ MIT License - see [LICENSE](./LICENSE) for details
 
 - **Issues**: [GitHub Issues](https://github.com/hopperlabsxyz/lagoon-mcp/issues)
 - **Discussions**: [GitHub Discussions](https://github.com/hopperlabsxyz/lagoon-mcp/discussions)
-- **Documentation**: [Tool Docs](./docs/tools/) | [Development Guide](./docs/DEVELOPMENT.md)
+- **Documentation**: [Tool Docs](./docs/tools/) | [Developer Reference](./docs/agent-notes.md)
+- **Release history**: [CHANGELOG.md](./CHANGELOG.md)
 
 ## Acknowledgments
 

package/dist/cache/index.d.ts

@@ -45,6 +45,9 @@ export declare const cacheTTL: {
     readonly yieldPrediction: 3600;
     readonly portfolioOptimization: 300;
     readonly composition: 900;
+    readonly globalTvl: 300;
+    readonly indexingStatus: 60;
+    readonly historicalState: 3600;
 };
 /**
  * Search filters type for cache key generation
@@ -74,7 +77,7 @@ export declare const cacheKeys: {
     schema: () => string;
     compareVaults: (addresses: string[], chainIds: number[]) => string;
     priceHistory: (address: string, chainId: number, range: string) => string;
-    composition: (address: string) => string;
+    composition: (address: string, chainId: number) => string;
 };
 /**
  * Generate cache key based on cache tag and parameters

package/dist/cache/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,SAAS,MAAM,YAAY,CAAC;AAGnC;;GAEG;AACH,eAAO,MAAM,KAAK,WAKhB,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,QAAQ;;;;;;;;;;;;;CAaX,CAAC;AAEX;;GAEG;AACH,KAAK,aAAa,GAAG;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,SAAS;yBACC,MAAM,WAAW,MAAM,KAAG,MAAM;6BAE5B,MAAM,KAAG,MAAM;4BAEhB,aAAa,KAAG,MAAM;gCAElB,MAAM,WAAW,MAAM,SAAS,MAAM,KAAG,MAAM;iGAWxE;QACD,YAAY,EAAE,MAAM,CAAC;QACrB,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,cAAc,EAAE,MAAM,CAAC;KACxB,KAAG,MAAM;kBAGE,MAAM;+BAES,MAAM,EAAE,YAAY,MAAM,EAAE,KAAG,MAAM;4BAMxC,MAAM,WAAW,MAAM,SAAS,MAAM,KAAG,MAAM;2BAGhD,MAAM,KAAG,MAAM;CACvC,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GAAG,MAAM,CAa7F;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,SAAS,CAAC,KAAK,CAE/C;AAED;;GAEG;AACH,wBAAgB,UAAU,IAAI,IAAI,CAEjC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,SAAS,MAAM,YAAY,CAAC;AAGnC;;GAEG;AACH,eAAO,MAAM,KAAK,WAKhB,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;CAgBX,CAAC;AAEX;;GAEG;AACH,KAAK,aAAa,GAAG;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,SAAS;yBACC,MAAM,WAAW,MAAM,KAAG,MAAM;6BAE5B,MAAM,KAAG,MAAM;4BAEhB,aAAa,KAAG,MAAM;gCAElB,MAAM,WAAW,MAAM,SAAS,MAAM,KAAG,MAAM;iGAWxE;QACD,YAAY,EAAE,MAAM,CAAC;QACrB,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,cAAc,EAAE,MAAM,CAAC;KACxB,KAAG,MAAM;kBAGE,MAAM;+BAES,MAAM,EAAE,YAAY,MAAM,EAAE,KAAG,MAAM;4BAMxC,MAAM,WAAW,MAAM,SAAS,MAAM,KAAG,MAAM;2BAGhD,MAAM,WAAW,MAAM,KAAG,MAAM;CAExD,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GAAG,MAAM,CAa7F;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,SAAS,CAAC,KAAK,CAE/C;AAED;;GAEG;AACH,wBAAgB,UAAU,IAAI,IAAI,CAEjC"}

package/dist/cache/index.js

@@ -51,6 +51,9 @@ export const cacheTTL = {
     yieldPrediction: 3600, // 60 minutes - ML-based forecast, expensive computation
     portfolioOptimization: 300, // 5 minutes - user-specific, interactive use case
     composition: 900, // 15 minutes - protocol composition from Octav API (backend caches 6h)
+    globalTvl: 300, // 5 minutes - protocol-wide TVL; ticks slowly but markets move
+    indexingStatus: 60, // 60 seconds - indexer health, block-by-block freshness needed
+    historicalState: 3600, // 60 minutes - historical state by timestamp is immutable once past
 };
 /**
  * Cache key generators
@@ -70,7 +73,7 @@ export const cacheKeys = {
         return `compare:${sortedAddresses}:${sortedChainIds}`;
     },
     priceHistory: (address, chainId, range) => `price_history:${address}:${chainId}:${range}`,
-    composition: (address) => `composition:${address.toLowerCase()}`,
+    composition: (address, chainId) => `composition:${address.toLowerCase()}:${chainId}`,
 };
 /**
  * Generate cache key based on cache tag and parameters

package/dist/cache/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,SAAS,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAEtC;;GAEG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,IAAI,SAAS,CAAC;IACjC,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM;IAC3B,WAAW,EAAE,MAAM,CAAC,KAAK,CAAC,WAAW;IACrC,SAAS,EAAE,KAAK,EAAE,2BAA2B;IAC7C,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO;CAC9B,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,SAAS,EAAE,GAAG,EAAE,sDAAsD;IACtE,aAAa,EAAE,GAAG,EAAE,iDAAiD;IACrE,aAAa,EAAE,GAAG,EAAE,qDAAqD;IACzE,WAAW,EAAE,IAAI,EAAE,qDAAqD;IACxE,YAAY,EAAE,GAAG,EAAE,0CAA0C;IAC7D,MAAM,EAAE,KAAK,EAAE,+CAA+C;IAC9D,UAAU,EAAE,GAAG,EAAE,+CAA+C;IAChE,YAAY,EAAE,IAAI,EAAE,sDAAsD;IAC1E,YAAY,EAAE,GAAG,EAAE,uDAAuD;IAC1E,eAAe,EAAE,IAAI,EAAE,wDAAwD;IAC/E,qBAAqB,EAAE,GAAG,EAAE,kDAAkD;IAC9E,WAAW,EAAE,GAAG,EAAE,uEAAuE;CACjF,CAAC;AASX;;;;GAIG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,SAAS,EAAE,CAAC,OAAe,EAAE,OAAe,EAAU,EAAE,CAAC,SAAS,OAAO,IAAI,OAAO,EAAE;IAEtF,aAAa,EAAE,CAAC,OAAe,EAAU,EAAE,CAAC,aAAa,OAAO,EAAE;IAElE,YAAY,EAAE,CAAC,OAAsB,EAAU,EAAE,CAAC,UAAU,OAAO,CAAC,UAAU,EAAE;IAEhF,gBAAgB,EAAE,CAAC,OAAe,EAAE,OAAe,EAAE,KAAa,EAAU,EAAE,CAC5E,QAAQ,OAAO,IAAI,OAAO,IAAI,KAAK,EAAE;IAEvC,YAAY,EAAE,CAAC,EACb,YAAY,EACZ,OAAO,EACP,UAAU,EACV,KAAK,EACL,IAAI,EACJ,OAAO,EACP,cAAc,GASf,EAAU,EAAE,CACX,gBAAgB,YAAY,IAAI,OAAO,IAAI,UAAU,IAAI,KAAK,IAAI,IAAI,IAAI,OAAO,IAAI,cAAc,EAAE;IAEvG,MAAM,EAAE,GAAW,EAAE,CAAC,eAAe;IAErC,aAAa,EAAE,CAAC,SAAmB,EAAE,QAAkB,EAAU,EAAE;QACjE,MAAM,eAAe,GAAG,CAAC,GAAG,SAAS,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACxD,MAAM,cAAc,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACrE,OAAO,WAAW,eAAe,IAAI,cAAc,EAAE,CAAC;IACxD,CAAC;IAED,YAAY,EAAE,CAAC,OAAe,EAAE,OAAe,EAAE,KAAa,EAAU,EAAE,CACxE,iBAAiB,OAAO,IAAI,OAAO,IAAI,KAAK,EAAE;IAEhD,WAAW,EAAE,CAAC,OAAe,EAAU,EAAE,CAAC,eAAe,OAAO,CAAC,WAAW,EAAE,EAAE;CACjF,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAW,EAAE,MAAuC;IACnF,0DAA0D;IAC1D,IAAI,GAAG,KAAK,OAAO,IAAI,SAAS,IAAI,MAAM,IAAI,SAAS,IAAI,MAAM,EAAE,CAAC;QAClE,OAAO,SAAS,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;IAC7E,CAAC;IAED,wCAAwC;IACxC,MAAM,YAAY,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC;SACxC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;SACtC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,IAAI,KAAK,EAAE,CAAC;SACxC,IAAI,CAAC,GAAG,CAAC,CAAC;IAEb,OAAO,GAAG,GAAG,CAAC,WAAW,EAAE,IAAI,YAAY,EAAE,CAAC;AAChD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa;IAC3B,OAAO,KAAK,CAAC,QAAQ,EAAE,CAAC;AAC1B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU;IACxB,KAAK,CAAC,QAAQ,EAAE,CAAC;AACnB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"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"}

package/dist/graphql/fragments/apr-breakdown.fragment.d.ts

@@ -12,6 +12,9 @@
 export interface APRBreakdown {
     linearNetApr: number;
     linearNetAprWithoutExtraYields: number;
+    twrrNetApr?: number | null;
+    twrrNetAprWithoutExtraYields?: number | null;
+    twrrGrossAprWithoutExtraYields?: number | null;
     airdrops: Array<{
         name: string;
         apr: number;
@@ -60,5 +63,5 @@ export interface APRBreakdown {
  * }
  * ```
  */
-export declare const APR_BREAKDOWN_FRAGMENT = "\n  fragment APRBreakdownFragment on APRs {\n    linearNetApr\n    linearNetAprWithoutExtraYields\n    airdrops {\n      name\n      apr\n      description\n      distributionTimestamp\n      endTimestamp\n      isEstimation\n      logoUrl\n      multiplier\n      ppsIncrease\n      startTimestamp\n    }\n    incentives {\n      name\n      apr\n      aprDescription\n      description\n      endTimestamp\n      incentiveRate {\n        incentiveAmount\n        referenceToken {\n          id\n        }\n        referenceTokenAmount\n      }\n    }\n    nativeYields {\n      name\n      apr\n      aprDescription\n      description\n      endTimestamp\n      isEstimation\n      logoUrl\n      multiplier\n      startTimestamp\n    }\n  }\n";
+export declare const APR_BREAKDOWN_FRAGMENT = "\n  fragment APRBreakdownFragment on APRs {\n    linearNetApr\n    linearNetAprWithoutExtraYields\n    twrrNetApr\n    twrrNetAprWithoutExtraYields\n    twrrGrossAprWithoutExtraYields\n    airdrops {\n      name\n      apr\n      description\n      distributionTimestamp\n      endTimestamp\n      isEstimation\n      logoUrl\n      multiplier\n      ppsIncrease\n      startTimestamp\n    }\n    incentives {\n      name\n      apr\n      aprDescription\n      description\n      endTimestamp\n      incentiveRate {\n        incentiveAmount\n        referenceToken {\n          id\n        }\n        referenceTokenAmount\n      }\n    }\n    nativeYields {\n      name\n      apr\n      aprDescription\n      description\n      endTimestamp\n      isEstimation\n      logoUrl\n      multiplier\n      startTimestamp\n    }\n  }\n";
 //# sourceMappingURL=apr-breakdown.fragment.d.ts.map

package/dist/graphql/fragments/apr-breakdown.fragment.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apr-breakdown.fragment.d.ts","sourceRoot":"","sources":["../../../src/graphql/fragments/apr-breakdown.fragment.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,8BAA8B,EAAE,MAAM,CAAC;IACvC,QAAQ,EAAE,KAAK,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;QACb,GAAG,EAAE,MAAM,CAAC;QACZ,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,qBAAqB,EAAE,MAAM,CAAC;QAC9B,YAAY,EAAE,MAAM,CAAC;QACrB,YAAY,EAAE,OAAO,CAAC;QACtB,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;QAC1B,WAAW,EAAE,MAAM,CAAC;QACpB,cAAc,EAAE,MAAM,CAAC;KACxB,CAAC,CAAC;IACH,UAAU,EAAE,KAAK,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,GAAG,EAAE,MAAM,CAAC;QACZ,cAAc,EAAE,MAAM,CAAC;QACvB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,YAAY,EAAE,MAAM,CAAC;QACrB,aAAa,EAAE;YACb,eAAe,EAAE,MAAM,CAAC;YACxB,cAAc,EAAE;gBACd,EAAE,EAAE,MAAM,CAAC;aACZ,CAAC;YACF,oBAAoB,EAAE,MAAM,CAAC;SAC9B,CAAC;KACH,CAAC,CAAC;IACH,YAAY,EAAE,KAAK,CAAC;QAClB,IAAI,EAAE,MAAM,CAAC;QACb,GAAG,EAAE,MAAM,CAAC;QACZ,cAAc,EAAE,MAAM,CAAC;QACvB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;QAC5B,YAAY,EAAE,OAAO,CAAC;QACtB,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;QAC1B,cAAc,EAAE,MAAM,CAAC;KACxB,CAAC,CAAC;CACJ;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,8uBA0ClC,CAAC"}
+{"version":3,"file":"apr-breakdown.fragment.d.ts","sourceRoot":"","sources":["../../../src/graphql/fragments/apr-breakdown.fragment.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,8BAA8B,EAAE,MAAM,CAAC;IAGvC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,4BAA4B,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7C,8BAA8B,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/C,QAAQ,EAAE,KAAK,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;QACb,GAAG,EAAE,MAAM,CAAC;QACZ,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,qBAAqB,EAAE,MAAM,CAAC;QAC9B,YAAY,EAAE,MAAM,CAAC;QACrB,YAAY,EAAE,OAAO,CAAC;QACtB,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;QAC1B,WAAW,EAAE,MAAM,CAAC;QACpB,cAAc,EAAE,MAAM,CAAC;KACxB,CAAC,CAAC;IACH,UAAU,EAAE,KAAK,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,GAAG,EAAE,MAAM,CAAC;QACZ,cAAc,EAAE,MAAM,CAAC;QACvB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,YAAY,EAAE,MAAM,CAAC;QACrB,aAAa,EAAE;YACb,eAAe,EAAE,MAAM,CAAC;YACxB,cAAc,EAAE;gBACd,EAAE,EAAE,MAAM,CAAC;aACZ,CAAC;YACF,oBAAoB,EAAE,MAAM,CAAC;SAC9B,CAAC;KACH,CAAC,CAAC;IACH,YAAY,EAAE,KAAK,CAAC;QAClB,IAAI,EAAE,MAAM,CAAC;QACb,GAAG,EAAE,MAAM,CAAC;QACZ,cAAc,EAAE,MAAM,CAAC;QACvB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;QAC5B,YAAY,EAAE,OAAO,CAAC;QACtB,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;QAC1B,cAAc,EAAE,MAAM,CAAC;KACxB,CAAC,CAAC;CACJ;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,o0BA6ClC,CAAC"}

package/dist/graphql/fragments/apr-breakdown.fragment.js

@@ -20,6 +20,9 @@ export const APR_BREAKDOWN_FRAGMENT = `
   fragment APRBreakdownFragment on APRs {
     linearNetApr
     linearNetAprWithoutExtraYields
+    twrrNetApr
+    twrrNetAprWithoutExtraYields
+    twrrGrossAprWithoutExtraYields
     airdrops {
       name
       apr

package/dist/graphql/fragments/apr-breakdown.fragment.js.map

@@ -1 +1 @@
-{"version":3,"file":"apr-breakdown.fragment.js","sourceRoot":"","sources":["../../../src/graphql/fragments/apr-breakdown.fragment.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA+CH;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0CrC,CAAC"}
+{"version":3,"file":"apr-breakdown.fragment.js","sourceRoot":"","sources":["../../../src/graphql/fragments/apr-breakdown.fragment.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAoDH;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6CrC,CAAC"}

package/dist/graphql/fragments/composition.fragment.d.ts

@@ -1,145 +1,32 @@
 /**
  * Composition Fragment
  *
- * Type definitions for vault composition data from Octav API.
- * The backend returns a JSONObject with chains as keys containing composition data.
- *
- * Note: The vaultComposition endpoint returns JSONObject type, so no GraphQL fragment
- * is needed. The response is a flat object keyed by chain name.
- */
-/**
- * Chain composition data from Octav API
- * Each chain entry contains aggregated position values and metadata
- */
-export interface ChainComposition {
-    /** Display name of the chain (e.g., "Ethereum", "Arbitrum") */
-    name: string;
-    /** Unique key for the chain (e.g., "ethereum", "arbitrum") */
-    key: string;
-    /** Chain ID as string (e.g., "1", "42161") */
-    chainId: string;
-    /** Total USD value of positions on this chain */
-    value: string;
-    /** Percentile ranking of this chain's value */
-    valuePercentile: string;
-    /** Total cost basis (may be "N/A") */
-    totalCostBasis: string;
-    /** Total closed PnL (may be "N/A") */
-    totalClosedPnl: string;
-    /** Total open PnL (may be "N/A") */
-    totalOpenPnl: string;
-}
-/**
- * Raw vaultComposition response - JSONObject keyed by chain name
- *
- * Example:
- * ```typescript
- * {
- *   "ethereum": { name: "Ethereum", key: "ethereum", chainId: "1", value: "6224.80", ... },
- *   "arbitrum": { name: "Arbitrum", key: "arbitrum", chainId: "42161", value: "3.99", ... },
- *   "linea": { name: "Linea", key: "linea", chainId: "59144", value: "0", ... },
- *   // ... 60+ chains
- * }
- * ```
+ * Typed shape of `Vault.composition: CompositionData` (the v0.6+ replacement
+ * for the retired `vaultComposition(walletAddress)` JSONObject query).
  */
-export type RawVaultComposition = Record<string, ChainComposition>;
 /**
- * Position category within a chain (e.g., LENDING, YIELD, DEPOSIT, SPOT)
- */
-export interface ProtocolPositionCategory {
-    /** Category name (e.g., "Lending", "Yield", "Deposit", "Spot") */
-    name: string;
-    /** Total USD value in this category */
-    totalValue: string;
-}
-/**
- * Chain-level breakdown within a protocol
- */
-export interface ProtocolChainData {
-    /** Chain display name (e.g., "Ethereum") */
-    name: string;
-    /** Chain key (e.g., "ethereum") */
-    key: string;
-    /** USD value on this chain */
-    value: string;
-    /** Total cost basis (may be "N/A") */
-    totalCostBasis: string;
-    /** Total closed PnL (may be "N/A") */
-    totalClosedPnl: string;
-    /** Total open PnL (may be "N/A") */
-    totalOpenPnl: string;
-    /** Position categories on this chain (keyed by category type) */
-    protocolPositions: Record<string, ProtocolPositionCategory>;
-}
-/**
- * Protocol-level composition data from Octav API
- * Represents a DeFi protocol like Spark, Morpho, Yield Basis, or "wallet" for idle assets
- *
- * Example protocols: spark, morphoblue, yieldbasis, lagoon, hyperliquid, wallet
- */
-export interface ProtocolCompositionData {
-    /** Protocol display name (e.g., "Spark", "Morpho", "Yield Basis", "Wallet") */
-    name: string;
-    /** Protocol key/identifier (e.g., "spark", "morphoblue", "wallet") */
-    key: string;
-    /** Total USD value in this protocol */
-    value: string;
-    /** Total cost basis (may be "N/A") */
-    totalCostBasis: string;
-    /** Total closed PnL (may be "N/A") */
-    totalClosedPnl: string;
-    /** Total open PnL (may be "N/A") */
-    totalOpenPnl: string;
-    /** Chain-level breakdown within this protocol */
-    chains: Record<string, ProtocolChainData>;
-}
-/**
- * Full vaultComposition response structure from Octav API
- *
- * Contains two main sections:
- * - assetByProtocols: Protocol-level breakdown (preferred for analysis)
- * - chains: Chain-level summary (legacy, kept for backward compatibility)
- *
- * Example:
- * ```typescript
- * {
- *   address: "0x...",
- *   networth: "4970636.89",
- *   assetByProtocols: {
- *     "spark": { name: "Spark", value: "1324461.98", chains: { ethereum: {...} } },
- *     "wallet": { name: "Wallet", value: "6356.97", chains: { ethereum: {...} } },
- *     // ... other protocols
- *   },
- *   chains: {
- *     "ethereum": { name: "Ethereum", chainId: "1", value: "4970455.03", ... },
- *     // ... other chains
- *   }
- * }
- * ```
- */
-export interface VaultCompositionFullResponse {
-    /** Vault/wallet address */
-    address: string;
-    /** Total portfolio net worth in USD */
-    networth: string;
-    /** Protocol-level breakdown (PRIMARY - use for diversification analysis) */
-    assetByProtocols: Record<string, ProtocolCompositionData>;
-    /** Chain-level summary (LEGACY - kept for backward compatibility) */
-    chains: Record<string, ChainComposition>;
-}
-/**
- * @deprecated Use ChainComposition instead - backend API changed
- * Protocol composition within a vault (legacy structure)
+ * Protocol-level allocation within `Vault.composition`. Sorted by
+ * `repartition` descending in the backend response.
  */
 export interface ProtocolComposition {
+    /** Protocol display name (e.g., "morphoblue", "spark", "Other") */
     protocol: string;
+    /** USD value deployed to this protocol */
     valueInUsd: number;
+    /** Percentage of total vault value (0–100) */
     repartition: number;
+    /** Drill-down for grouped items (currently only used by the "Other" bucket) */
     details?: ProtocolComposition[];
+    /** Protocol logo URL (from Octav) */
+    logoUrl?: string | null;
 }
 /**
- * @deprecated Use ChainComposition instead - backend API changed
- * Token/position composition within a vault (legacy structure)
+ * Token/position-level allocation within `Vault.composition`.
+ *
+ * Caveat (per live probe May 2026): `contract` and `chainKey` are empty
+ * strings in production, and `symbol`/`name` are human-readable display
+ * strings (e.g., "Spark - reth"), not real ERC20 contracts. Useful for
+ * display but NOT for programmatic cross-referencing.
  */
 export interface TokenComposition {
     symbol: string;
@@ -149,18 +36,20 @@ export interface TokenComposition {
     valueInUsd: number;
     repartition: number;
     details?: TokenComposition[];
+    logoUrl?: string | null;
 }
 /**
- * @deprecated Use RawVaultComposition instead - backend API changed
- * Complete composition data for a vault (legacy structure)
+ * Top-level shape of `Vault.composition`. `totalValueInUsd` is nullable —
+ * the backend returns null when no Octav data has been fetched yet.
  */
 export interface CompositionData {
     compositions: ProtocolComposition[];
     tokenCompositions: TokenComposition[];
+    totalValueInUsd: number | null;
 }
 /**
- * @deprecated No longer used - backend returns JSONObject, not a typed GraphQL response
- * GraphQL fragment for composition data (legacy)
+ * GraphQL fragment for the typed CompositionData. Inlined inside a
+ * `vaultByAddress { composition { ... } }` query — NOT a standalone query.
  */
-export declare const COMPOSITION_FRAGMENT = "\n  fragment CompositionFragment on CompositionData {\n    compositions {\n      protocol\n      valueInUsd\n      repartition\n      details {\n        protocol\n        valueInUsd\n        repartition\n      }\n    }\n    tokenCompositions {\n      symbol\n      name\n      contract\n      chainKey\n      valueInUsd\n      repartition\n      details {\n        symbol\n        name\n        contract\n        chainKey\n        valueInUsd\n        repartition\n      }\n    }\n  }\n";
+export declare const COMPOSITION_FRAGMENT = "\n  fragment CompositionFragment on CompositionData {\n    totalValueInUsd\n    compositions {\n      protocol\n      valueInUsd\n      repartition\n      logoUrl\n      details {\n        protocol\n        valueInUsd\n        repartition\n        logoUrl\n      }\n    }\n    tokenCompositions {\n      symbol\n      name\n      contract\n      chainKey\n      valueInUsd\n      repartition\n      logoUrl\n      details {\n        symbol\n        name\n        contract\n        chainKey\n        valueInUsd\n        repartition\n        logoUrl\n      }\n    }\n  }\n";
 //# sourceMappingURL=composition.fragment.d.ts.map

package/dist/graphql/fragments/composition.fragment.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"composition.fragment.d.ts","sourceRoot":"","sources":["../../../src/graphql/fragments/composition.fragment.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,GAAG,EAAE,MAAM,CAAC;IACZ,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,eAAe,EAAE,MAAM,CAAC;IACxB,sCAAsC;IACtC,cAAc,EAAE,MAAM,CAAC;IACvB,sCAAsC;IACtC,cAAc,EAAE,MAAM,CAAC;IACvB,oCAAoC;IACpC,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;AAOnE;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,sCAAsC;IACtC,cAAc,EAAE,MAAM,CAAC;IACvB,sCAAsC;IACtC,cAAc,EAAE,MAAM,CAAC;IACvB,oCAAoC;IACpC,YAAY,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC;CAC7D;AAED;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACtC,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,GAAG,EAAE,MAAM,CAAC;IACZ,uCAAuC;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,sCAAsC;IACtC,cAAc,EAAE,MAAM,CAAC;IACvB,sCAAsC;IACtC,cAAc,EAAE,MAAM,CAAC;IACvB,oCAAoC;IACpC,YAAY,EAAE,MAAM,CAAC;IACrB,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;CAC3C;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,4BAA4B;IAC3C,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,uCAAuC;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAAC;IAC1D,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CAC1C;AAOD;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,mBAAmB,EAAE,CAAC;CACjC;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,gBAAgB,EAAE,CAAC;CAC9B;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,YAAY,EAAE,mBAAmB,EAAE,CAAC;IACpC,iBAAiB,EAAE,gBAAgB,EAAE,CAAC;CACvC;AAED;;;GAGG;AACH,eAAO,MAAM,oBAAoB,0eA6BhC,CAAC"}
+{"version":3,"file":"composition.fragment.d.ts","sourceRoot":"","sources":["../../../src/graphql/fragments/composition.fragment.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAYH;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC;IACjB,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB,8CAA8C;IAC9C,WAAW,EAAE,MAAM,CAAC;IACpB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,mBAAmB,EAAE,CAAC;IAChC,qCAAqC;IACrC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,YAAY,EAAE,mBAAmB,EAAE,CAAC;IACpC,iBAAiB,EAAE,gBAAgB,EAAE,CAAC;IACtC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED;;;GAGG;AACH,eAAO,MAAM,oBAAoB,+jBAkChC,CAAC"}

package/dist/graphql/fragments/composition.fragment.js

@@ -1,26 +1,26 @@
 /**
  * Composition Fragment
  *
- * Type definitions for vault composition data from Octav API.
- * The backend returns a JSONObject with chains as keys containing composition data.
- *
- * Note: The vaultComposition endpoint returns JSONObject type, so no GraphQL fragment
- * is needed. The response is a flat object keyed by chain name.
+ * Typed shape of `Vault.composition: CompositionData` (the v0.6+ replacement
+ * for the retired `vaultComposition(walletAddress)` JSONObject query).
  */
 /**
- * @deprecated No longer used - backend returns JSONObject, not a typed GraphQL response
- * GraphQL fragment for composition data (legacy)
+ * GraphQL fragment for the typed CompositionData. Inlined inside a
+ * `vaultByAddress { composition { ... } }` query — NOT a standalone query.
  */
 export const COMPOSITION_FRAGMENT = `
   fragment CompositionFragment on CompositionData {
+    totalValueInUsd
     compositions {
       protocol
       valueInUsd
       repartition
+      logoUrl
       details {
         protocol
         valueInUsd
         repartition
+        logoUrl
       }
     }
     tokenCompositions {
@@ -30,6 +30,7 @@ export const COMPOSITION_FRAGMENT = `
       chainKey
       valueInUsd
       repartition
+      logoUrl
       details {
         symbol
         name
@@ -37,6 +38,7 @@ export const COMPOSITION_FRAGMENT = `
         chainKey
         valueInUsd
         repartition
+        logoUrl
       }
     }
   }

package/dist/graphql/fragments/composition.fragment.js.map

@@ -1 +1 @@
-{"version":3,"file":"composition.fragment.js","sourceRoot":"","sources":["../../../src/graphql/fragments/composition.fragment.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA4KH;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6BnC,CAAC"}
+{"version":3,"file":"composition.fragment.js","sourceRoot":"","sources":["../../../src/graphql/fragments/composition.fragment.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA0DH;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkCnC,CAAC"}