kira-wallet 0.1.0

package/viewer/README.md

@@ -0,0 +1,119 @@
+# Wallet research viewer
+
+A local browser view of registered wallets and their latest analysis. The default server is read-only. Opt-in local controls enable explicit research, exact names and Watching connections. The Kira interface uses warm ivory surfaces, ink text, a restrained violet accent, native system fonts and an adult webtoon research companion. Each view includes a factual note computed from saved research, with an explanation of valuation limits. Model chat remains awaiting account setup. Signing and trading are not exposed.
+
+## Open the viewer
+
+Run from the project directory:
+
+```sh
+python3 viewer/start.py
+```
+
+Open [Wallets](http://127.0.0.1:8765). The launcher keeps the server running in the background and reuses it if already running. For a foreground server use `python3 viewer/server.py --port 8765`. The server binds only to this computer. It uses Python's standard library and needs no frontend build or package installation.
+
+Home is the first sidebar item and the default view. It shows the estimated total value, registered wallet count, networks with holdings, position count, wallet shares, network allocations, and the five largest holdings. Click a wallet card or sidebar item to open its holdings. The selected view and value filter stay in the browser.
+
+Click a token name or a largest-holding card to open its token overview. It sums the recorded balance and known value for that exact chain ID and contract, then shows every registered wallet, recorded prices, analysis times, market links, curve backing and recorded burn refunds where available. An absent holding remains a missing record rather than a fabricated zero. The price range can reflect different observation times. Shared curve backing is never added once per wallet.
+
+Click a network name in Home or a wallet's chain heading to open its network overview. It shows aggregate known value, unique assets, positions, holding wallets, each wallet's coverage and allocation, and the combined token list. Search tokens by name, symbol or contract. The dollar filters apply to the combined token value across wallets; summary totals remain unfiltered. The network selector includes all configured mainnets and testnets, including networks without recorded holdings.
+
+Detail views have local hash URLs such as `/#/network/8453` and `/#/token/8453/<contract>`. Direct links, browser Back/Forward and reload preserve the selected entity. Research file updates retain the selected detail view. These figures use existing snapshots; opening a detail does not refresh providers.
+
+One compact breadcrumb in the topbar provides `Home / wallet`, `Home / network`, or `Home / network / token` navigation. Page headings follow directly below it. Mobile hides the redundant topbar research summary; observation times remain in the page content.
+
+## Network images
+
+Mint Club's current network selector uses static artwork under `https://mint.club/assets/networks/`, not a chain-logo API. Base uses `base.svg`; other visible mainnets use PNG files such as `ethereum@2x.png`. The mapping in `chain_images.py` was checked against the live selector and public frontend bundles on 2026-10-03. All 16 visible mainnet files return image content. Testnets inherit parent artwork, matching Mint Club's Sepolia treatment. Ham and Over files referenced by an internal bundle currently return HTML, so they retain the letter fallback. Image failures preserve the fallback without affecting research data. Images use the existing approved Mint Club origin.
+
+Holdings are grouped by chain and sorted by estimated USD value. Use All, ≥ $5, or ≥ $10 to filter by the value of the whole held position. The default is ≥ $10. Unpriced positions appear in All and do not qualify for dollar filters.
+
+Home sums direct mainnet positions across wallets. A position is one asset in one wallet. Unique assets use chain ID and contract address, so the same asset held by two wallets counts once as a unique asset and twice as positions. Unknown network values show a dash. Testnets, curve backing, and pool TVL are excluded from the total. Allocation percentages refer to priced value, and the footer shows the range of recorded price update times.
+
+Market links open Mint Club or the observed DEX pool evidence. A DEX link can lead to DEX Screener or the pool contract explorer when that pool is absent from the market index. Research notes link to the complete recorded report.
+
+## Add an analysis or refresh it
+
+The source of truth is `wallets.json`. Each wallet's `latest_snapshot.result` points to a `results.json` with the recorded schema, and its `latest_snapshot.directory` points to that snapshot folder. Keep wallet addresses and operator tags in the registry. The viewer reads all registered wallets, with no hardcoded wallet list.
+
+Save a new dated analysis and update that wallet's latest snapshot pointer. The open viewer checks the files every five seconds and updates the sidebar and holdings without a page reload. It keeps the selected wallet and filters. Files should be written through a temporary file and atomic rename. A partial JSON write briefly keeps the last valid response.
+
+The agent can refresh market prices for existing analysed holdings:
+
+```sh
+python3 viewer/refresh_prices.py --wallet '<registered address or tag>'
+```
+
+Omit `--wallet` to refresh all analysed wallets. This reads public DEX prices and current Mint Club curve prices through RPC, then atomically writes `market-prices.json` next to each snapshot. The viewer updates automatically. This command refreshes prices only. A full holdings refresh requires a new wallet analysis. The analysis date and price date are shown separately.
+
+The browser never contacts an RPC or price provider and never reads RPC credentials. Token image requests use the approved Mint Club and Hunt image endpoints and image origins returned by Mint Club. Research processes use the configured RPC references. The server exposes allowlisted static assets, derived data and registered reports. With local controls enabled, protected job endpoints accept explicit same-origin actions.
+
+## Token images
+
+Mint Club holdings use `/api/tokens/logo?chainId=...&address=...`. Reserve assets use the image catalog collected from `/api/reserve-tokens/list`, `/api/reserve-tokens/stats`, `/api/reserve-tokens/popular`, and the `reserveToken` metadata in `/api/tokens/details/{chainId}/{address}`. Legacy 1inch URLs currently return HTTP 403 and are resolved through the Hunt token-image endpoint for the same chain and contract. Native assets retain their own symbol icons rather than adopting a wrapped token's logo.
+
+The wallet analysis pipeline collects image metadata automatically and reuses successful metadata for 24 hours. The agent can refresh it independently:
+
+```sh
+python3 viewer/token_images.py --force
+```
+
+Add `--wallet <registered address or exact tag>` to collect details for one wallet. The shared catalog is `cache/token-images.json`; it contains public metadata and does not alter any research snapshot. Images load lazily with a fixed size and no referrer. Missing or failed images fall back to the existing symbol. API failures preserve previous logos and do not stop a wallet analysis.
+
+## Valuation rules
+
+Use a valid DEX market price when available. Mint Club positions without a DEX price use the current curve spot price multiplied by the reserve asset's USD price. Nested CHICKEN curves resolve through the price of CHICKEN. The resulting value is a spot estimate, not a full sell or burn quote. Curve reserves are never added to the wallet's position values.
+
+Unknown prices and unfunded curves remain unpriced. A source-reported pool whose own token accounts for more than 98 percent of its reported TVL is excluded as a USD price reference because the quote side provides little support for that price. This is a conservative valuation rule, not a determination about the token. Testnet positions are excluded from dollar totals. Missing chain coverage remains incomplete rather than becoming a zero balance.
+
+## Verification
+
+```sh
+python3 -m unittest discover -s viewer -p 'test_*.py'
+node --check viewer/static/app.js
+```
+
+The checks cover reserve price conversion, unknown prices, testnet exclusion, multi-wallet aggregation, shared asset identities, image catalog updates, failed image metadata refreshes, approved image origins, price and registry changes, path boundaries, conditional HTTP responses, and blocked write endpoints. Desktop and mobile layout, Home navigation, images and the filters are also checked in the browser.
+
+Detail checks also cover exact decimal balance aggregation, shared curve backing exclusion, same-contract separation across networks, and missing or unresearched wallet coverage. The token and network pages are checked at desktop, 390 px and 320 px widths.
+
+## Design references
+
+[lpTOKEN.fun](https://lptoken.fun) informed the restrained presentation. [Apple](https://www.apple.com) informed typography and spacing. [Selected Lazyweb references](https://www.lazyweb.com/agentic-search/5eed25a9-311b-4741-a717-8e16fb777b35) informed the sidebar and holdings hierarchy.
+
+[Home dashboard references](https://www.lazyweb.com/agentic-search/1d5075aa-195b-4d2f-8ce9-e1d7bf8ac03e) informed the aggregate balance, account cards, and sidebar hierarchy. Image endpoints are documented in the [Mint Club API](https://sdk.mint.club/docs/api).
+
+[Compact navigation references](https://www.lazyweb.com/agentic-search/b67b3f2d-9998-4da7-a42c-871ef9c88c82) informed the single topbar breadcrumb and reduced header spacing.
+
+## Planned Kira Wallet product
+
+The [product specification](../docs/KIRA_PRODUCT_SPEC.md) and [implementation plan](../docs/KIRA_IMPLEMENTATION_PLAN.md) describe portable RPC configuration, Kira's identity, the workspace, direct jobs and optional agent chat. Connected chat remains a separate outcome awaiting account and disclosure choices.
+
+## Opt-in local controls
+
+The legacy viewer start remains read-only. `kira start --controls` enables the
+version 1 job API with same-origin Host/Origin checks and a rotating local
+session. It offers research, exact names, connection references, cancel/resume
+and saved analysis comparison. No signing or trading is exposed. Jobs continue
+independently of the viewer and a disconnected model. The synthetic demo blocks
+provider research. See [the job contract](../docs/JOB_CONTRACT.md) and
+[continuation report](../docs/KIRA_JOBS_BUILD_REPORT.md).
+
+## Watching connections
+
+With local controls enabled, Add wallet offers manual entry or Browser wallet.
+Choose an EIP-6963-compatible browser wallet, then explicitly select a shared
+public account. Check the complete address and exact name before Add and
+research. Activity shows the accepted local job. Existing Watching addresses
+offer an open-wallet link to preserve their names.
+
+The extension session is memory only. Discovery, reload and reopening a completed
+session do not request accounts automatically. Account changes invalidate the
+preview; network changes only update session context. Disconnecting from Kira
+does not delete saved wallets or revoke extension permissions. Manage those
+permissions in the extension. No signature or transaction is requested.
+
+A browser without a compatible extension still supports manual entry. Sample
+mode permits form exploration but blocks account requests and provider research.
+The EIP contracts are [provider discovery](https://eips.ethereum.org/EIPS/eip-6963)
+and [provider events](https://eips.ethereum.org/EIPS/eip-1193).

package/viewer/chain_images.py

@@ -0,0 +1,21 @@
+"""Public network artwork used by Mint Club's chain selector."""
+
+# Verified against https://mint.club/explore on 2026-10-03.
+# Testnets use their parent network's artwork, as Mint Club does for Sepolia.
+# The current bundles mention Ham/Over/Degen files, but those URLs return HTML
+# rather than an image. Leave them unset so the viewer uses its letter fallback.
+NETWORK_ARTWORK = {
+    1: 'ethereum@2x.png', 8453: 'base.svg', 81457: 'blast@2x.png',
+    10: 'optimism@2x.png', 42161: 'arbitrum@2x.png', 43114: 'avalanche@2x.png',
+    137: 'polygon@2x.png', 56: 'bnb@2x.png', 109: 'shibarium@2x.png',
+    7560: 'cyber@2x.png', 8217: 'kaia@2x.png', 130: 'unichain@2x.png',
+    7777777: 'zora@2x.png', 33139: 'apechain@2x.png', 177: 'hashkey@2x.png',
+    4663: 'robinhood@2x.png', 11155111: 'ethereum@2x.png', 84532: 'base.svg',
+    168587773: 'blast@2x.png', 157: 'shibarium@2x.png',
+    43113: 'avalanche@2x.png', 111557560: 'cyber@2x.png',
+}
+
+
+def chain_image(chain_id):
+    artwork = NETWORK_ARTWORK.get(chain_id)
+    return 'https://mint.club/assets/networks/' + artwork if artwork else None

package/viewer/details.py

@@ -0,0 +1,119 @@
+"""Cross-wallet token and network views derived only from recorded holdings."""
+from decimal import Decimal, InvalidOperation
+import json
+from chain_images import chain_image
+
+
+def total_value(assets):
+    values = [a['value_usd'] for a in assets
+              if a.get('environment') == 'mainnet' and a.get('value_usd') is not None]
+    return sum(values) if values else None
+
+
+def total_balance(assets):
+    try:
+        quantities = [Decimal(a['balance']) for a in assets]
+        if not quantities or any(not q.is_finite() or q < 0 for q in quantities): return None
+        # Decimal's default precision could round large or very small holdings.
+        from decimal import localcontext
+        with localcontext() as context:
+            context.prec = max(80, sum(len(q.as_tuple().digits) + abs(q.as_tuple().exponent) for q in quantities) + 10)
+            return format(sum(quantities, Decimal(0)), 'f')
+    except (InvalidOperation, TypeError, KeyError): return None
+
+
+def wallet_identity(wallet):
+    return {k: wallet.get(k) for k in ('key', 'name', 'address', 'tags', 'analysed_at', 'prices_at')}
+
+
+def coverage_for(wallet, chain_id):
+    return next((c for c in wallet['chains'] if c['id'] == chain_id), None)
+
+
+def coverage_status(wallet, coverage):
+    if not wallet.get('analysed_at'): return 'Awaiting analysis'
+    if not coverage: return 'Not researched'
+    if not coverage.get('rpc_available'): return 'RPC unavailable'
+    if not coverage.get('complete'): return 'Incomplete discovery'
+    return 'Researched'
+
+
+def observed_range(rows, key):
+    dates = [r[key] for r in rows if r.get(key)]
+    return {'from': min(dates, default=None), 'to': max(dates, default=None)}
+
+
+def project_details(wallets, root):
+    catalog = {}
+    path = root / 'networks.json'
+    if path.exists():
+        for c in json.loads(path.read_text()).get('networks', []):
+            catalog[c['chain_id']] = {'id': c['chain_id'], 'name': c['name'], 'environment': c['environment']}
+    for wallet in wallets:
+        for c in wallet['chains']:
+            catalog.setdefault(c['id'], {k: c[k] for k in ('id', 'name', 'environment') if k in c})
+    for c in catalog.values(): c['image_url'] = chain_image(c['id'])
+
+    groups = {}
+    for wallet in wallets:
+        for asset in wallet['assets']:
+            groups.setdefault(asset['id'], []).append((wallet, asset))
+    tokens = []
+    for identity, holdings in groups.items():
+        first = holdings[0][1]
+        network = catalog.get(first['chain_id'], {'id': first['chain_id'], 'name': str(first['chain_id']), 'environment': 'unknown'})
+        assets = [a for _, a in holdings]
+        token = {k: first.get(k) for k in ('id', 'chain_id', 'symbol', 'name', 'address', 'is_native', 'image_url')}
+        token.update({'network': network, 'environment': network['environment'],
+                      'balance': total_balance(assets), 'value_usd': total_value(assets),
+                      'wallet_count': len(holdings), 'unpriced_count': sum(a.get('value_usd') is None for a in assets)})
+        links = {(link['label'], link['url']): link for a in assets for link in a['links']}
+        token['links'] = list(links.values())
+        rows = []
+        by_wallet = {w['key']: a for w, a in holdings}
+        for wallet in wallets:
+            asset = by_wallet.get(wallet['key'])
+            coverage = coverage_for(wallet, first['chain_id'])
+            row = wallet_identity(wallet)
+            row.update({'asset': asset, 'coverage': coverage_status(wallet, coverage),
+                        'balance_observed_at':asset.get('balance_observed_at') if asset else None,
+                        'price_observed_at':(asset.get('price') or {}).get('observed_at') if asset else None,
+                        'status': 'Held' if asset else 'No holding recorded' if coverage and coverage.get('complete') and coverage.get('rpc_available') else 'Unknown'})
+            rows.append(row)
+        token['wallets'] = rows
+        held_rows = [r for r in rows if r['asset']]
+        token['analysis_times'] = observed_range(held_rows, 'analysed_at')
+        token['price_times'] = observed_range(held_rows, 'price_observed_at')
+        tokens.append(token)
+    tokens.sort(key=lambda a: (-(a['value_usd'] if a['value_usd'] is not None else -1), a['id']))
+
+    networks = []
+    for chain_id, network in catalog.items():
+        row = dict(network)
+        chain_tokens = [t for t in tokens if t['chain_id'] == chain_id]
+        assets = [a for wallet in wallets for a in wallet['assets'] if a['chain_id'] == chain_id]
+        rows = []
+        for wallet in wallets:
+            coverage = coverage_for(wallet, chain_id)
+            held = [a for a in wallet['assets'] if a['chain_id'] == chain_id]
+            account = wallet_identity(wallet)
+            value = total_value(held)
+            if not held and coverage and coverage.get('complete') and coverage.get('rpc_available') and network['environment'] == 'mainnet': value = 0
+            account.update({'position_count': len(held), 'value_usd': value,
+                            'unpriced_count': sum(a.get('value_usd') is None for a in held),
+                            'coverage': coverage_status(wallet, coverage), 'has_holdings': bool(held)})
+            rows.append(account)
+        value = total_value(assets)
+        if not assets and rows and all(r['coverage'] == 'Researched' for r in rows) and network['environment'] == 'mainnet': value = 0
+        row.update({'value_usd': value, 'position_count': len(assets), 'unique_asset_count': len(chain_tokens),
+                    'wallet_count': sum(r['has_holdings'] for r in rows),
+                    'unpriced_count': sum(a.get('value_usd') is None for a in assets),
+                    'wallets': rows, 'tokens': chain_tokens,
+                    'analysis_times': observed_range(rows, 'analysed_at'),
+                    'price_times': observed_range([a.get('price') or {} for a in assets], 'observed_at')})
+        networks.append(row)
+    networks.sort(key=lambda c: (c['environment'] != 'mainnet', -(c['value_usd'] if c['value_usd'] is not None else -1), c['name']))
+    # Network tokens reference the same objects in memory. Serialize only their
+    # IDs; the client joins them against tokens rather than duplicating records.
+    for network in networks: network['token_ids'] = [t['id'] for t in network.pop('tokens')]
+    return {'tokens': tokens, 'networks': networks}

package/viewer/model.py

@@ -0,0 +1,216 @@
+"""Read-only projection of wallet research snapshots into viewer data."""
+from __future__ import annotations
+
+from decimal import Decimal, InvalidOperation
+from pathlib import Path
+import hashlib
+import json
+import math
+import os
+from token_images import image_for, read_catalog
+from chain_images import chain_image
+from details import project_details
+
+ROOT = Path(os.environ.get('KIRA_DATA_DIR',Path(__file__).resolve().parents[1])).expanduser().resolve()
+EXPLORERS = {1:'https://etherscan.io',8453:'https://basescan.org',81457:'https://blastscan.io',
+    10:'https://optimistic.etherscan.io',42161:'https://arbiscan.io',43114:'https://snowtrace.io',
+    137:'https://polygonscan.com',56:'https://bscscan.com',109:'https://shibariumscan.io',
+    7560:'https://cyberscan.co',8217:'https://kaiascan.io',130:'https://uniscan.xyz',
+    7777777:'https://explorer.zora.energy',33139:'https://apescan.io',177:'https://hashkey.blockscout.com',
+    4663:'https://robinhoodchain.blockscout.com',11155111:'https://sepolia.etherscan.io',
+    84532:'https://sepolia.basescan.org',168587773:'https://sepolia.blastscan.io',
+    157:'https://puppyscan.shib.io',43113:'https://testnet.snowtrace.io'}
+
+def read(path): return json.loads(path.read_text())
+def number(value):
+    try:
+        n = float(Decimal(str(value)))
+        return n if math.isfinite(n) and n >= 0 else None
+    except (InvalidOperation, TypeError, ValueError, OverflowError): return None
+
+def within(root, relative):
+    path = (root / relative).resolve()
+    if not path.is_relative_to(root.resolve()): raise ValueError('Snapshot path outside research directory')
+    return path
+
+def pool_has_liquidity(p):
+    return (p.get('reported_liquidity') or {}).get('usd',0)>0 or (p.get('factory_measurement') or {}).get('active_liquidity_verified',False)
+
+def dex_price(token, observed):
+    """Reject an extreme one-sided TVL as a USD price reference. Keep its evidence."""
+    candidates=[]; suspect=False
+    for p in token.get('dex_pools',[]):
+        price=number(p.get('reported_price_usd'))
+        pair=p.get('paired_tokens',[])
+        if price is None or len(pair)!=2 or pair[0]['address'].lower()!=token['token_address'].lower(): continue
+        liq=p.get('reported_liquidity') or {}
+        tvl=number(liq.get('usd')); base=number(liq.get('base'))
+        # Source-reported TVL can consist almost entirely of the self-priced token.
+        # Do not use such a pool as the wallet's market value.
+        if tvl and base is not None and base*price/tvl>0.98:
+            suspect=True; continue
+        if tvl and pool_has_liquidity(p): candidates.append((tvl,price,p))
+    if candidates:
+        _,price,p=max(candidates,key=lambda v:v[0])
+        return {'usd':price,'basis':'DEX market','source':p['source_url'],'observed_at':observed,'quality':'estimated'}
+    if suspect:return {'usd':None,'basis':'Thin quote side','quality':'unreliable','observed_at':observed}
+    for p in token.get('indexer_price_references',[]):
+        price=number(p.get('value'))
+        if p.get('currency')=='usd' and price is not None and price>0:
+            return {'usd':price,'basis':'Market index','source':'https://www.alchemy.com','observed_at':p.get('lastUpdatedAt'),'quality':'estimated'}
+    return None
+
+def project_wallet(entry, snapshot, root=ROOT, images=None):
+    images=read_catalog(root) if images is None else images
+    latest=entry.get('latest_snapshot') or {}
+    snapshot_dir=within(root,latest.get('directory','snapshots'))
+    market_path=snapshot_dir/'market-prices.json'
+    market=read(market_path) if market_path.exists() else {}
+    prices={(p.get('chain_id',8453),p['address'].lower()):p for p in market.get('tokens',[])}
+    refs=snapshot.get('price_references',{})
+    eth=number(market.get('native_usd',{}).get('ETH',{}).get('usd')) or number(refs.get('ETH_USD',{}).get('value'))
+    price_time=market.get('observed_at') or refs.get('ETH_USD',{}).get('observed_at') or snapshot.get('compiled_at')
+    tokens=snapshot.get('tokens',[])
+    by_address={(t['chain_id'],t['token_address'].lower()):t for t in tokens}
+    cache={}
+    def price_for(t,seen=None):
+        k=(t['chain_id'],t['token_address'].lower())
+        if k in cache:return cache[k]
+        seen=set(seen or set())
+        if k in seen:return None
+        seen.add(k)
+        override=prices.get(k)
+        mint=t.get('mintclub')
+        if override and override.get('basis')!='Curve spot':
+            cache[k]=override;return override
+        if mint:
+            reserve=mint['reserve_symbol'];reserve_price=None
+            reserve_identity=(t['chain_id'],mint['reserve_token'].lower())
+            if reserve_identity==(8453,'0x4200000000000000000000000000000000000006'):reserve_price=eth
+            elif reserve_identity==(8453,'0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf'):reserve_price=number(refs.get('cbBTC_USD',{}).get('value'))
+            rt=prices.get((t['chain_id'],mint['reserve_token'].lower()))
+            if rt and rt.get('usd') is not None:reserve_price=number(rt['usd'])
+            parent=by_address.get((t['chain_id'],mint['reserve_token'].lower()))
+            if parent:
+                parent_price=price_for(parent,seen)
+                if parent_price:reserve_price=parent_price.get('usd')
+            if reserve_price is not None:
+                spot=number((override or {}).get('curve_price_in_reserve',mint['price_for_next_mint_in_reserve_token']))
+                funded=number(override['curve_reserve'])>0 if override and 'curve_reserve' in override else mint.get('funded')
+                p={'usd':spot*reserve_price if spot is not None else None,'basis':'Curve spot',
+                   'source':mint['source_url'],'observed_at':(override or {}).get('observed_at',mint['observed_at']),
+                   'quality':'estimated' if funded else 'unfunded'}
+                if not funded:p['usd']=None
+                cache[k]=p;return p
+        p=dex_price(t,snapshot.get('compiled_at'))
+        cache[k]=p;return p
+
+    assets=[]
+    for t in tokens:
+        p=price_for(t);quantity=number(t['wallet_balance'])
+        value=quantity*p['usd'] if p and p.get('usd') is not None and quantity is not None else None
+        label=t['symbol'];name=t.get('name') or label
+        market_token=prices.get((t['chain_id'],t['token_address'].lower())) or {}
+        if 'http' in label.lower() or 'claim' in label.lower():label='Airdrop';name='Unverified token'
+        links=[]
+        if t.get('mintclub'):links.append({'label':'Mint Club','url':t['mintclub']['source_url']})
+        found={}
+        for pool in t.get('dex_pools',[]):
+            if not pool_has_liquidity(pool):continue
+            venue=pool['venue'].lower(); label_venue='Uniswap' if 'uniswap' in venue else 'Aerodrome' if 'aerodrome' in venue else venue.replace('-',' ').title()
+            weight=(pool.get('reported_liquidity') or {}).get('usd',0)
+            measured=pool.get('factory_measurement') or {}
+            if not weight and measured.get('quote_balance'):
+                weight=(number(measured['quote_balance']) or 0)*(eth or 0) if measured.get('quote_symbol')=='WETH' else number(measured['quote_balance']) or 0
+            if label_venue not in found or weight>found[label_venue][0]:found[label_venue]=(weight,pool['source_url'])
+        links += [{'label':k,'url':v[1]} for k,v in found.items()]
+        explorer=EXPLORERS.get(t['chain_id'])
+        if explorer:links.append({'label':'Explorer','url':explorer+'/token/'+t['token_address']})
+        assets.append({'id':f'{t["chain_id"]}:{t["token_address"].lower()}','chain_id':t['chain_id'],
+            'symbol':label,'name':name,'address':t['token_address'],'balance':t['wallet_balance'],
+            'price':p,'value_usd':value,'is_native':False,'links':links,
+            'balance_observed_at':t.get('balance_observed_at') or snapshot.get('compiled_at'),
+            'burn_quote':(t.get('mintclub') or {}).get('wallet_full_burn'),
+            'image_url':image_for(images,t['chain_id'],t['token_address'],mint=bool(t.get('mintclub'))),
+            'curve_reserve': {'amount':market_token.get('curve_reserve',t['mintclub']['reserve_balance']),'symbol':t['mintclub']['reserve_symbol']} if t.get('mintclub') else None})
+    coverage=snapshot.get('coverage',[])
+    for c in coverage:
+        raw=c.get('native_balance');quantity=number(raw)
+        if quantity is None or quantity<=0:continue
+        sym=c['native_symbol'];ref=market.get('native_usd',{}).get(sym)
+        px=number(ref.get('usd')) if ref else eth if sym=='ETH' else number(refs.get(sym+'_USD',{}).get('value'))
+        assets.append({'id':f'{c["chain_id"]}:native','chain_id':c['chain_id'],'symbol':sym,'name':'Ether' if sym=='ETH' else sym,
+            'address':None,'balance':raw,'is_native':True,'curve_reserve':None,
+            'image_url':image_for(images,c['chain_id'],native_symbol=sym),
+            'price':{'usd':px,'basis':'Market index','quality':'estimated','observed_at':price_time} if px is not None else None,
+            'value_usd':quantity*px if px is not None and c['environment']=='mainnet' else None,
+            'links':[{'label':'Explorer','url':EXPLORERS[c['chain_id']]+'/address/'+entry['address']}] if c['chain_id'] in EXPLORERS else []})
+    chains=[]
+    for c in coverage:
+        rows=[a for a in assets if a['chain_id']==c['chain_id']]
+        for a in rows:
+            a['environment']=c['environment']
+            if c['environment']=='testnet':a['value_usd']=None
+        chains.append({'id':c['chain_id'],'name':c['name'],'environment':c['environment'],
+            'image_url':chain_image(c['chain_id']),
+            'assets':len(rows),'value_usd':sum(a['value_usd'] or 0 for a in rows) if c['environment']=='mainnet' else None,
+            'complete':c['general_erc20_discovery']=='indexer_checked','rpc_available':c['rpc_status']=='available'})
+    total=sum(a['value_usd'] or 0 for a in assets if a['environment']=='mainnet')
+    return {'address':entry['address'],'key':entry['address_key'],'tags':entry.get('tags',[]),
+        'name':(entry.get('tags') or [entry['address'][:10]])[0],'analysed_at':snapshot.get('compiled_at'),
+        'prices_at':price_time,'balance_observed_at':max((t.get('balance_observed_at','') for t in tokens),default=snapshot.get('compiled_at')),
+        'known_value_usd':total,'unpriced_count':sum(a['value_usd'] is None for a in assets),
+        'assets':assets,'chains':chains,'counts':snapshot.get('counts',{}),'status':snapshot.get('status'),
+        'report_url':'/api/report/'+entry['address_key']}
+
+def dashboard(wallets):
+    """Sum direct mainnet positions, without adding pool liquidity or curve backing."""
+    chains={};assets={};positions=[]
+    for wallet in wallets:
+        names={c['id']:c['name'] for c in wallet['chains']}
+        for asset in wallet['assets']:
+            if asset.get('environment')!='mainnet':continue
+            positions.append(asset)
+            chain=chains.setdefault(asset['chain_id'],{'id':asset['chain_id'],'name':names[asset['chain_id']],
+                'position_count':0,'wallet_keys':set(),'values':[],'unpriced_count':0})
+            chain['position_count']+=1;chain['wallet_keys'].add(wallet['key'])
+            row=assets.setdefault(asset['id'],{k:asset[k] for k in ['id','chain_id','symbol','name','image_url']})
+            row.setdefault('wallet_keys',set()).add(wallet['key'])
+            row.setdefault('values',[]);row.setdefault('unpriced_count',0)
+            if asset['value_usd'] is None:
+                chain['unpriced_count']+=1;row['unpriced_count']+=1
+            else:
+                chain['values'].append(asset['value_usd']);row['values'].append(asset['value_usd'])
+    def finish(row):
+        row['value_usd']=sum(row['values']) if row['values'] else None
+        row['wallet_count']=len(row.pop('wallet_keys'));row.pop('values')
+        return row
+    network_rows=sorted((finish(c) for c in chains.values()),key=lambda c:c['value_usd'] or 0,reverse=True)
+    asset_rows=sorted((finish(a) for a in assets.values()),key=lambda a:a['value_usd'] or 0,reverse=True)
+    for asset in asset_rows:asset['chain_name']=chains[asset['chain_id']]['name']
+    values=[a['value_usd'] for a in positions if a['value_usd'] is not None]
+    dates=[w['prices_at'] for w in wallets if w.get('prices_at')]
+    return {'known_value_usd':sum(values) if values else None,'wallet_count':len(wallets),
+        'analysed_wallet_count':sum(bool(w.get('analysed_at')) for w in wallets),
+        'position_count':len(positions),'unique_asset_count':len(assets),'chain_count':len(chains),
+        'priced_count':len(values),'unpriced_count':len(positions)-len(values),
+        'prices_from':min(dates,default=None),'prices_to':max(dates,default=None),
+        'networks':network_rows,'largest_holdings':[a for a in asset_rows if a['value_usd'] is not None][:5]}
+
+def load_state(root=ROOT):
+    registry=read(root/'wallets.json');wallets=[];images=read_catalog(root)
+    for entry in registry.get('wallets',[]):
+        latest=entry.get('latest_snapshot')
+        if latest and latest.get('result'):
+            result=read(within(root,latest['result']))
+            if result['wallet_address'].lower()!=entry['address_key']:raise ValueError('Snapshot wallet identity mismatch')
+            wallets.append(project_wallet(entry,result,root,images))
+        else:
+            wallets.append({'address':entry['address'],'key':entry['address_key'],'tags':entry.get('tags',[]),
+                'name':(entry.get('tags') or [entry['address'][:10]])[0],'assets':[],'chains':[],
+                'known_value_usd':0,'unpriced_count':0,'analysed_at':None,'status':'awaiting_analysis','counts':{}})
+    state={'wallets':wallets,'currency':'USD','dashboard':dashboard(wallets),
+           'details':project_details(wallets,root)}
+    if registry.get('demo') is True:state['demo']=True
+    encoded=json.dumps(state,ensure_ascii=False,allow_nan=False,separators=(',',':')).encode()
+    return state,encoded,hashlib.sha256(encoded).hexdigest()

package/viewer/refresh-curve-prices.cjs

@@ -0,0 +1,35 @@
+const fs=require('fs');
+const h=require('../onchain.cjs');
+const file=process.argv[2];
+(async()=>{
+ const snapshot=JSON.parse(fs.readFileSync(file));
+ const allRows=snapshot.tokens.filter(t=>t.mintclub);
+ const output=[];
+ const blocks={};
+ for(const chainId of [...new Set(allRows.map(t=>t.chain_id))]){
+ const rows=allRows.filter(t=>t.chain_id===chainId);
+ const c=await h.connect(chainId),block=await c.getBlockNumber();blocks[chainId]=block.toString();
+ for(let i=0;i<rows.length;i+=5){
+  const batch=rows.slice(i,i+5);
+  const res=await c.multicall({contracts:batch.map(t=>({address:t.mintclub.bond_address,abi:h.bondAbi,functionName:'getDetail',args:[t.token_address]})),multicallAddress:'0xcA11bde05977b3631167028862bE2a173976CA11',batchSize:0,blockNumber:block});
+  res.forEach((r,j)=>{
+   if(r.status==='success'){const v=r.result.info;output.push({chain_id:chainId,address:batch[j].token_address,basis:'Curve spot',curve_price_in_reserve:h.viem.formatUnits(v.priceForNextMint,v.reserveDecimals),curve_reserve:h.viem.formatUnits(v.reserveBalance,v.reserveDecimals),reserve_symbol:v.reserveSymbol,observed_at:new Date().toISOString(),block_number:block.toString()});}
+   else output.push({chain_id:chainId,address:batch[j].token_address,error:h.safeError(r.error)});
+  });
+ }
+ }
+ // MEMBER is absent from the market index. Read its verified V3 pool price.
+ const member=snapshot.tokens.find(t=>t.chain_id===8453&&t.symbol.toLowerCase()==='member');
+ if(member){
+  const c=await h.connect(8453),block=await c.getBlockNumber();
+  const pool='0xA4eFE9e8E2A2D5A2aC46805f233b8e49d0e11955';
+  const abi=h.viem.parseAbi(['function slot0() view returns (uint160,int24,uint16,uint16,uint16,uint8,bool)','function token0() view returns (address)','function token1() view returns (address)']);
+  const result=await c.multicall({contracts:['slot0','token0','token1'].map(functionName=>({address:pool,abi,functionName})),multicallAddress:'0xcA11bde05977b3631167028862bE2a173976CA11',batchSize:0,blockNumber:block});
+  if(result.every(r=>r.status==='success')){
+   const ratio=(Number(result[0].result[0])/2**96)**2;
+   const price=result[1].result.toLowerCase()===member.token_address.toLowerCase()?ratio:1/ratio;
+   output.push({chain_id:8453,address:member.token_address,basis:'DEX market',price_in_weth:price,source:'https://basescan.org/address/'+pool,observed_at:new Date().toISOString(),block_number:block.toString()});
+  }
+ }
+ console.log(h.serialize({observed_at:new Date().toISOString(),blocks,tokens:output}));
+})().catch(e=>{console.log(h.serialize(h.safeError(e)));process.exitCode=1;});

package/viewer/refresh_prices.py

@@ -0,0 +1,97 @@
+"""Refresh price references for registered snapshots. Agent CLI, never a viewer action."""
+from pathlib import Path
+from concurrent.futures import ThreadPoolExecutor
+import argparse
+import fcntl
+import json
+import os
+import subprocess
+import sys
+
+sys.path.insert(0,str(Path(__file__).resolve().parents[1]))
+import research as h
+from model import dex_price, within
+from curve_pricing import enrich
+DEX_CHAINS={1:'ethereum',8453:'base',10:'optimism',42161:'arbitrum',137:'polygon',56:'bsc',43114:'avalanche',81457:'blast',130:'unichain',7777777:'zora',33139:'apechain',177:'hashkey',8217:'kaia',7560:'cyber',109:'shibarium',4663:'robinhood'}
+
+parser=argparse.ArgumentParser();parser.add_argument('--wallet',help='Registered wallet address or tag. Omit to refresh all registered snapshots.')
+args=parser.parse_args()
+analysis_lock=os.fdopen(int(os.environ['KIRA_ANALYSIS_FD']), 'a') if os.environ.get('KIRA_ANALYSIS_FD') else (h.ROOT/'.analysis.lock').open('a')
+try:fcntl.flock(analysis_lock,fcntl.LOCK_EX|fcntl.LOCK_NB)
+except BlockingIOError:raise SystemExit('Another wallet or price analysis is running. Retry after it finishes.')
+registry=json.loads((h.ROOT/'wallets.json').read_text())
+selected=[w for w in registry['wallets'] if w.get('latest_snapshot') and (not args.wallet or args.wallet.lower()==w['address_key'] or args.wallet in w['tags'])]
+if not selected:raise SystemExit('No analysed registered wallet matches this selection.')
+
+for w in selected:
+ folder=within(h.ROOT,w['latest_snapshot']['directory']);path=within(h.ROOT,w['latest_snapshot']['result']);snapshot=json.loads(path.read_text())
+ pools={}
+ for t in snapshot['tokens']:
+  chain=DEX_CHAINS.get(t['chain_id'])
+  if chain:
+   pools.setdefault(chain,set()).update(p['pool'] for p in t['dex_pools'])
+ requests=[]
+ for chain,addresses in pools.items():
+  addresses=sorted(addresses)
+  requests += ['https://api.dexscreener.com/latest/dex/pairs/'+chain+'/'+','.join(addresses[i:i+25]) for i in range(0,len(addresses),25)]
+ reserves={(t['chain_id'],m['reserve_token']):m['reserve_symbol'] for t in snapshot['tokens'] if (m:=t.get('mintclub'))}
+ # Every wallet needs an independent ETH reference, even without a WETH-backed curve.
+ reserves[(8453,'0x4200000000000000000000000000000000000006')]='WETH'
+ for (chain_id,address),symbol in reserves.items():
+  chain=DEX_CHAINS.get(chain_id)
+  if chain:requests.append('https://api.dexscreener.com/token-pairs/v1/'+chain+'/'+address)
+ def get(url):return {'source':url,'observed_at':h.now(),'response':h.fetch(url)}
+ fetched=list(ThreadPoolExecutor(max_workers=5).map(get,requests))
+ pairs=[]
+ for r in fetched:
+  response=r['response'];pairs.extend(response if isinstance(response,list) else response.get('pairs') or [])
+ prices=[]
+ for t in snapshot['tokens']:
+  candidates=[p for p in pairs if p['chainId']==DEX_CHAINS.get(t['chain_id']) and p['baseToken']['address'].lower()==t['token_address'].lower()]
+  shadow={**t,'dex_pools':[{'reported_price_usd':p.get('priceUsd'),'paired_tokens':[p['baseToken'],p['quoteToken']],
+             'reported_liquidity':p.get('liquidity'),'source_url':p['url']} for p in candidates], 'indexer_price_references':[]}
+  p=dex_price(shadow,h.now())
+  if p:prices.append({'chain_id':t['chain_id'],'address':t['token_address'],**p})
+ for (chain_id,address),symbol in reserves.items():
+  options=[p for p in pairs if p['chainId']==DEX_CHAINS.get(chain_id) and p['baseToken']['address'].lower()==address.lower() and p.get('priceUsd') and p.get('liquidity',{}).get('usd',0)>0]
+  if options:
+   shadow={'token_address':address,'dex_pools':[{'reported_price_usd':p.get('priceUsd'),'paired_tokens':[p['baseToken'],p['quoteToken']],'reported_liquidity':p.get('liquidity'),'source_url':p['url']} for p in options]}
+   p=dex_price(shadow,h.now())
+   if p:prices.append({'chain_id':chain_id,'address':address,**p,'reserve_symbol':symbol})
+ node=subprocess.run(['node',str(Path(__file__).with_name('refresh-curve-prices.cjs')),str(path)],capture_output=True,text=True,timeout=60)
+ rpc=json.loads(node.stdout)
+ if node.returncode!=0:raise SystemExit('Curve refresh failed: '+h.redact(rpc))
+ by_address={(p['chain_id'],p['address'].lower()):p for p in prices}
+ eth=next((p['usd'] for p in prices if p.get('chain_id')==8453 and p['address'].lower()=='0x4200000000000000000000000000000000000006' and p.get('usd') is not None),None)
+ if eth is None:raise SystemExit('ETH price refresh failed. Previous market cache preserved.')
+ for p in rpc['tokens']:
+  key=(p['chain_id'],p['address'].lower())
+  if 'error' in p:continue
+  if p.get('price_in_weth') is not None:p['usd']=p['price_in_weth']*eth;p['quality']='estimated'
+  # Keep a valid DEX quote as the market price; retain current curve spot metadata.
+  if key in by_address and by_address[key].get('usd') is not None and p['basis']=='Curve spot':
+   by_address[key].update({k:v for k,v in p.items() if k.startswith('curve_') or k in ['reserve_symbol','block_number']})
+  else:by_address[key]=p
+ native_prices={k.removesuffix('_USD'):{'usd':float(p['value']),'observed_at':p.get('observed_at')} for k,p in snapshot.get('price_references',{}).items() if p.get('value') is not None}
+ previous=folder/'market-prices.json'
+ if previous.exists():native_prices.update(json.loads(previous.read_text()).get('native_usd',{}))
+ native_prices['ETH']={'usd':eth,'observed_at':h.now()}
+ output={'observed_at':h.now(),'wallet_address':w['address'],'balance_refresh':False,
+         'native_usd':native_prices,'tokens':list(by_address.values()),
+         'source_requests':fetched,'rpc_price_state':rpc,
+         'note':'Prices only. Balances and research coverage remain at their recorded analysis time.'}
+ destination=folder/'market-prices.json';temporary=destination.with_suffix('.json.tmp')
+ output=enrich(snapshot,output,folder)
+ if os.environ.get('KIRA_JOB_SNAPSHOT'):
+  from kira_jobs import atomic
+  job_folder=(h.ROOT/os.environ['KIRA_JOB_SNAPSHOT']).resolve()
+  if not job_folder.is_relative_to(h.ROOT/'snapshots'):raise ValueError('Job path must be within snapshots/.')
+  overlay=job_folder/'prices.json'
+  output['snapshot_id']=w['latest_snapshot']['directory']
+  output['job_result_status']='completed_with_coverage_gaps' if rpc.get('errors') or any('error' in p for p in rpc['tokens']) or any(isinstance(r['response'],dict) and 'transport_error' in r['response'] for r in fetched) else 'completed'
+  atomic(overlay,output)
+  atomic(job_folder/'price-publication.json',{'schema_version':1,'snapshot_id':w['latest_snapshot']['directory'],
+      'overlay':str(overlay.relative_to(h.ROOT)),'projection':str(destination.relative_to(h.ROOT)),
+      'status':output['job_result_status']})
+ temporary.write_text(json.dumps(output,indent=2)+'\n');os.replace(temporary,destination)
+ print(json.dumps({'wallet':w['address'],'tag':w['tags'],'price_records':len(output['tokens']),'observed_at':output['observed_at'],'errors':sum(isinstance(r['response'],dict) and 'transport_error' in r['response'] for r in fetched)}))