release: 1.8.8

Author: iJaack

README.md

@@ -1,8 +1,8 @@
 # Evalanche
 
-**Multi-EVM agent wallet SDK with onchain identity (ERC-8004), full agent identity resolution, payment rails (x402), cross-chain liquidity (Li.Fi bridging + DEX aggregation + DeFi Composer), gas funding (Gas.zip), market intelligence (CoinGecko), prediction markets (Polymarket CLOB), agent economy primitives, DeFi operations, and perpetual futures (dYdX v4)**
+**Multi-EVM agent wallet SDK with onchain identity (ERC-8004), unified wallet holdings discovery, full agent identity resolution, payment rails (x402), cross-chain liquidity (Li.Fi bridging + DEX aggregation + DeFi Composer), gas funding (Gas.zip), market intelligence (CoinGecko), prediction markets (Polymarket CLOB), agent economy primitives, DeFi operations, and perpetual futures (dYdX v4 + Hyperliquid)**
 
-Evalanche gives AI agents a **non-custodial** wallet on **any EVM chain** — Ethereum, Base, Arbitrum, Optimism, Polygon, BSC, Avalanche, and 15+ more — with built-in onchain identity, ERC-8004 full registration resolution, payment capabilities, cross-chain bridging, same-chain DEX swaps (31+ aggregators), CoinGecko market data, Polymarket market discovery and execution, agent economy primitives (discovery, negotiation, settlement, escrow, memory), DeFi operations, and perpetual futures on dYdX. No browser, no popups, no human in the loop.
+Evalanche gives AI agents a **non-custodial** wallet on **any EVM chain** — Ethereum, Base, Arbitrum, Optimism, Polygon, BSC, Avalanche, and 15+ more — with built-in onchain identity, ERC-8004 full registration resolution, payment capabilities, unified holdings scanning, cross-chain bridging, same-chain DEX swaps (31+ aggregators), CoinGecko market data, Polymarket market discovery and execution, agent economy primitives (discovery, negotiation, settlement, escrow, memory), DeFi operations, and perpetual futures on dYdX + Hyperliquid. No browser, no popups, no human in the loop.
 
 ## Install
 
@@ -383,6 +383,45 @@ await baseVaults.deposit(YOUSD, '1000'); // approve + deposit in one call
 await baseVaults.withdraw(YOUSD, '998.1'); // redeem shares
 ```
 
+### Unified Holdings (universal registry + scanner)
+
+Evalanche now ships a universal in-repo holdings registry and a one-pass holdings scanner. The scanner combines:
+
+- native balances across supported chains
+- seeded ERC-20 balances
+- DeFi positions such as ERC-4626 vaults and liquid staking receipts
+- Polymarket positions
+- perp venue positions on Hyperliquid and dYdX
+
+```typescript
+const agent = new Evalanche({ privateKey: '0x...', network: 'base' });
+
+const portfolio = await agent.holdings().scan();
+
+console.log(portfolio.summary);
+// → { totalHoldings, byType, byChain, byProtocol }
+
+const filtered = await agent.holdings().scan({
+  chains: ['polygon', 'base', 'avalanche', 'hyperliquid'],
+  include: ['native', 'token', 'defi', 'prediction', 'perp'],
+  protocols: ['polymarket', 'avantis', 'yousd'],
+});
+
+console.log(filtered.holdings[0]);
+// → {
+//   holdingType: 'vault' | 'token' | 'prediction' | 'perp' | ...,
+//   protocolId: 'yousd-vault',
+//   protocolName: 'yoUSD Vault',
+//   chain: 'base',
+//   symbol: 'yoUSD',
+//   displayBalance: '24.917987',
+//   underlyingValue: '26.771162',
+//   ...
+// }
+```
+
+The universal registry is checked into the repo and shared by every agent. It is seeded with local canonical records, a vendored AvaPilot Avalanche snapshot, and DefiLlama import tooling. Runtime holdings truth still comes from live onchain reads and venue APIs.
+
 ### Prediction Markets: Polymarket (v1.5.0+)
 
 Polymarket support is exposed in two ways:
@@ -644,6 +683,9 @@ AGENT_PRIVATE_KEY=0x... evalanche-mcp --http --port 3402
 |------|-------------|
 | `get_address` | Get agent wallet address |
 | `get_balance` | Get native token balance |
+| `get_holdings` | Unified wallet holdings scan across tokens, DeFi, predictions, and perps |
+| `search_registry` | Search the universal in-repo holdings registry |
+| `registry_status` | Get universal registry counts and detector coverage |
 | `send_avax` | Send native tokens |
 | `call_contract` | Call a contract method |
 | `sign_message` | Sign a message |
@@ -893,7 +935,13 @@ For live operator validation, use the runbook in [docs/live-smoke-checklist.md](
 - market search, market details, order book access, balance and position discovery
 - expanded Evalanche into prediction market workflows alongside DeFi + perps
 
-### v1.8.6 (current)
+### v1.8.8 (current)
+- **Universal holdings + live verification**
+- unified holdings scanning now combines native balances, seeded ERC-20s, DeFi positions, Polymarket positions, and perp venue positions behind `agent.holdings().scan()` and the MCP `get_holdings` tool
+- the in-repo universal registry now seeds both DeFi routing and holdings discovery, with local canonical records taking precedence over AvaPilot and DefiLlama-enriched metadata
+- npm-facing documentation now reflects the current package surface instead of the older DeFi-routing-only model
+
+### v1.8.6
 - **Report-closure remediation**
 - DeFi MCP tools now resolve known protocols to canonical chains, support interoperable address inputs, and fail clearly on explicit wrong-chain requests
 - Avalanche dapp resolution is enriched by a vendored AvaPilot-backed registry provider without introducing runtime GitHub/network dependency

RELEASE_NOTES_1.8.8.md

@@ -0,0 +1,30 @@
+# Evalanche v1.8.8
+
+## Highlights
+
+- Added a universal in-repo holdings registry shared by all agents
+- Added unified holdings scanning through `agent.holdings().scan()`
+- Added MCP tools:
+  - `get_holdings`
+  - `search_registry`
+  - `registry_status`
+- Unified DeFi routing and holdings discovery onto the same universal registry
+- Added DefiLlama import tooling for maintainers via `npm run sync:defillama-registry`
+- Updated the README and npm package metadata to match the shipped package surface
+
+## Holdings Coverage
+
+The unified scanner now covers:
+
+- native balances across supported EVM chains
+- seeded ERC-20 balances
+- ERC-4626 vault positions such as yoUSD and Avantis `avUSDC`
+- liquid staking receipts such as sAVAX
+- Polymarket positions
+- Hyperliquid and dYdX perp positions
+
+## Notes
+
+- The registry source of truth remains the repo
+- DefiLlama is used for seed/enrichment, not runtime wallet ownership
+- Wallet ownership is always confirmed through live onchain or venue reads

package-lock.json

@@ -1,7 +1,7 @@
 {
   "name": "evalanche",
-  "version": "1.8.7",
-  "description": "Multi-EVM agent wallet SDK with onchain identity (ERC-8004), payment rails (x402), cross-chain bridging (Li.Fi + Gas.zip), and perpetual futures (dYdX v4)",
+  "version": "1.8.8",
+  "description": "Multi-EVM agent wallet SDK with unified holdings discovery, onchain identity (ERC-8004), x402 payments, cross-chain liquidity (Li.Fi + Gas.zip), prediction markets, DeFi, and perpetual futures",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -23,7 +23,8 @@
     "build": "tsup",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "sync:defillama-registry": "node scripts/sync-defillama-registry.mjs"
   },
   "keywords": [
     "avalanche",

package.json

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const root = path.resolve(__dirname, '..');
+const seedDir = path.join(root, 'src', 'holdings', 'registry', 'seed');
+const protocolOut = path.join(seedDir, 'defillama.protocols.generated.json');
+const sourcesOut = path.join(seedDir, 'defillama.sources.generated.json');
+
+const SUPPORTED_CHAINS = new Map([
+  ['ethereum', 'ethereum'],
+  ['base', 'base'],
+  ['arbitrum', 'arbitrum'],
+  ['optimism', 'optimism'],
+  ['polygon', 'polygon'],
+  ['avalanche', 'avalanche'],
+  ['bsc', 'bsc'],
+  ['gnosis', 'gnosis'],
+  ['fantom', 'fantom'],
+  ['linea', 'linea'],
+  ['scroll', 'scroll'],
+  ['celo', 'celo'],
+  ['mantle', 'mantle'],
+]);
+
+function normalizeSlug(value) {
+  return String(value ?? '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '');
+}
+
+function normalizeChain(value) {
+  const lowered = String(value ?? '').trim().toLowerCase();
+  return SUPPORTED_CHAINS.get(lowered);
+}
+
+function protocolRecord(protocol) {
+  const chains = Array.from(new Set(
+    (Array.isArray(protocol.chains) ? protocol.chains : [])
+      .map(normalizeChain)
+      .filter(Boolean),
+  ));
+  if (chains.length === 0) return null;
+
+  return {
+    protocolId: normalizeSlug(protocol.slug || protocol.name),
+    name: String(protocol.name),
+    slug: normalizeSlug(protocol.slug || protocol.name),
+    category: String(protocol.category ?? 'defi').toLowerCase(),
+    chains,
+    website: typeof protocol.url === 'string' ? protocol.url : undefined,
+    aliases: [protocol.slug, protocol.symbol].filter(Boolean).map((value) => String(value).toLowerCase()),
+    source: 'defillama',
+  };
+}
+
+function sourceRecord(pool) {
+  const chain = normalizeChain(pool.chain);
+  const protocolId = normalizeSlug(pool.project);
+  if (!chain || !protocolId) return null;
+  const tokens = Array.isArray(pool.underlyingTokens) ? pool.underlyingTokens : [];
+  const lowerTokens = tokens.filter((item) => typeof item === 'string' && item.startsWith('0x'));
+  if (lowerTokens.length === 0) return null;
+
+  return {
+    sourceId: `defillama-${protocolId}-${normalizeSlug(pool.poolMeta || pool.symbol || pool.pool) || pool.pool}`,
+    protocolId,
+    chain,
+    sourceKind: 'lp_receipt',
+    detectorId: 'lp_receipt_detector',
+    role: pool.poolMeta || pool.symbol || 'pool',
+    underlyingTokens: lowerTokens.map((token) => `${chain}:${token}`),
+    priority: 10,
+    source: 'defillama',
+  };
+}
+
+async function main() {
+  const [protocols, poolsPayload] = await Promise.all([
+    fetch('https://api.llama.fi/protocols').then((res) => res.json()),
+    fetch('https://yields.llama.fi/pools').then((res) => res.json()),
+  ]);
+
+  const normalizedProtocols = Array.from(new Map(
+    protocols
+      .map(protocolRecord)
+      .filter(Boolean)
+      .map((record) => [record.protocolId, record]),
+  ).values());
+
+  const normalizedSources = Array.from(new Map(
+    (Array.isArray(poolsPayload?.data) ? poolsPayload.data : [])
+      .map(sourceRecord)
+      .filter(Boolean)
+      .map((record) => [record.sourceId, record]),
+  ).values());
+
+  await fs.mkdir(seedDir, { recursive: true });
+  await fs.writeFile(protocolOut, `${JSON.stringify(normalizedProtocols, null, 2)}\n`);
+  await fs.writeFile(sourcesOut, `${JSON.stringify(normalizedSources, null, 2)}\n`);
+
+  console.log(JSON.stringify({
+    protocols: normalizedProtocols.length,
+    sources: normalizedSources.length,
+    protocolOut,
+    sourcesOut,
+  }, null, 2));
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.stack || error.message : String(error));
+  process.exitCode = 1;
+});

scripts/sync-defillama-registry.mjs

@@ -32,6 +32,8 @@ import type { PlatformCLI as PlatformCLIType } from './avalanche/platform-cli';
 import type { InteropIdentityResolver as InteropResolverType } from './interop/identity';
 import type { LiquidStakingClient } from './defi/liquid-staking';
 import type { VaultClient } from './defi/vaults';
+import type { PolymarketClient } from './polymarket';
+import type { HoldingsClient } from './holdings/client';
 
 /** Configuration for the Evalanche agent */
 export interface EvalancheConfig {
@@ -86,6 +88,8 @@ export class Evalanche {
   private _interopResolver?: InteropResolverType;
   private _defiStaking?: LiquidStakingClient;
   private _defiVaults?: VaultClient;
+  private _polymarketClient?: PolymarketClient;
+  private _holdingsClient?: HoldingsClient;
   private readonly _mnemonic?: string;
   private readonly _multiVM: boolean;
   private _multiVMInitialized = false;
@@ -636,6 +640,29 @@ export class Evalanche {
     return { staking: this._defiStaking, vaults: this._defiVaults };
   }
 
+  /**
+   * Get or create the Polymarket client (lazy-initialized).
+   */
+  async polymarket(): Promise<PolymarketClient> {
+    if (!this._polymarketClient) {
+      const { PolymarketClient } = await import('./polymarket/client');
+      this._polymarketClient = new PolymarketClient(this.wallet, 137);
+    }
+    return this._polymarketClient;
+  }
+
+  /**
+   * Get the unified holdings scanner backed by the universal registry.
+   */
+  holdings(): HoldingsClient {
+    if (!this._holdingsClient) {
+      // eslint-disable-next-line @typescript-eslint/no-var-requires
+      const { HoldingsClient: HC } = require('./holdings/client') as typeof import('./holdings/client');
+      this._holdingsClient = new HC(this);
+    }
+    return this._holdingsClient;
+  }
+
   /**
    * Find a perpetual market ticker across connected perp venues.
    */