kira-wallet 0.2.2 → 0.2.3

package/README.md

@@ -15,7 +15,7 @@ web app to manage wallets, inspect token markets and follow research. Your
 existing AI agent can use the same records and actions through the Kira CLI or
 optional MCP connection, then open the web app beside your conversation.
 
-**This branch prepares 0.2.2.** Kira now supplies wallet tools and a full-window
+**Kira 0.2.2 is published on npm; this branch prepares 0.2.3.** Kira supplies wallet tools and a full-window
 management app. Your agent host manages its own conversations, models, files and
 approvals. Kira does not launch a model CLI or require a model login.
 
@@ -104,7 +104,9 @@ saved holdings; it does not discover additional tokens. Price refresh preserves
 recorded balances and does not recover missing holdings.
 
 DEX price references require at least $1,000 of reported pool liquidity and
-exclude extremely one-sided pools. A displayed value is an estimate, not a
+exclude extremely one-sided pools. Research and price refresh both fall back to
+Alchemy index prices when no DEX price or explicit liquidity rejection exists.
+An index price is a reference, not proof of a liquid market. A displayed value is an estimate, not a
 promise of sale proceeds. Observation timestamps remain attached to the facts.
 
 ## Upgrading from 0.1.20

package/cashout.py

@@ -3,6 +3,7 @@ from decimal import Decimal, InvalidOperation, localcontext
 import json
 from pathlib import Path
 import re
+from market_records import checked_price
 
 CRITERIA = {'version': 2, 'minimum_quoted_usd': '1', 'mintclub_redemption_included': True,
             'gas_included': False, 'execution_verified': False,
@@ -36,6 +37,7 @@ def output_price(chain_id, address, market):
     rows = [p for p in market.get('tokens', []) if p.get('chain_id') == chain_id
             and isinstance(p.get('address'), str) and p['address'].lower() == address.lower()]
     for row in rows:
+        row = checked_price(row)
         price = decimal(row.get('usd'))
         if (price is not None and price > 0 and row.get('quality') == 'estimated'
                 and row.get('basis') in ('DEX market', 'Market index')

package/curve_pricing.py

@@ -3,11 +3,41 @@ from concurrent.futures import ThreadPoolExecutor
 import json
 import math
 from pathlib import Path
-import subprocess
 import sys
 import research as h
 
 
+def index_prices(identities, folder, deadline=None):
+    """Read bounded Alchemy batches by exact chain/contract, retaining source time."""
+    from wallet import ALCHEMY, atomic, fetch
+    sys.path.insert(0,str(h.ASSETS/'viewer'))
+    from model import dex_price
+    import hashlib
+    import re
+    wanted=sorted({(cid,address.lower()) for cid,address in identities
+                   if cid in ALCHEMY and isinstance(address,str) and re.fullmatch(r'0x[0-9a-fA-F]{40}',address)})
+    key=h.secrets().get('ALCHEMY_CUSTOM_APY_KEY') if wanted else None
+    prices={}
+    for start in range(0,len(wanted) if key else 0,25):
+        batch=wanted[start:start+25]
+        requests=[{'network':ALCHEMY[cid],'address':address} for cid,address in batch]
+        file=Path(folder)/('reserve-price-cache-'+hashlib.sha256(json.dumps(requests,sort_keys=True).encode()).hexdigest()+'.json')
+        record=json.loads(file.read_text()) if file.exists() else None
+        if record is None:
+            response=fetch('https://api.g.alchemy.com/prices/v1/'+key+'/tokens/by-address',{'addresses':requests},deadline=deadline)
+            record={'observed_at':h.now(),'source':'Alchemy token prices by address','request':requests,'response':response}
+            if isinstance(response,dict) and isinstance(response.get('data'),list):atomic(file,record)
+        response=record.get('response')
+        expected={(ALCHEMY[cid],address):(cid,address) for cid,address in batch}
+        for row in response.get('data',[]) if isinstance(response,dict) and isinstance(response.get('data'),list) else []:
+            if not isinstance(row,dict) or row.get('error') or not isinstance(row.get('network'),str) or not isinstance(row.get('address'),str):continue
+            identity=expected.get((row['network'],row['address'].lower()))
+            if identity is None or not isinstance(row.get('prices'),list):continue
+            price=dex_price({'token_address':identity[1],'indexer_price_references':[p for p in row['prices'] if isinstance(p,dict)]},None)
+            if price:prices[identity]={'chain_id':identity[0],'address':identity[1],**price}
+    return {'tokens':list(prices.values()),'status':'partial' if len(prices)<len(wanted) else 'checked'}
+
+
 def resolve(graph, prices):
     nodes={(r['chain_id'],r['address'].lower()):r for r in graph if r.get('address')}
     known={(r['chain_id'],r['address'].lower()):r for r in prices}
@@ -47,6 +77,8 @@ def resolve(graph, prices):
                 'source':node['source'],'observed_at':node['observed_at'],'block_number':node['block_number'],
                 'curve_price_in_reserve':node['price_in_reserve'],'curve_reserve':node['curve_reserve'],'reserve_symbol':node['reserve_symbol'],
                 'price_path':[node['address']]+parent.get('price_path',[node['reserve_token']])}
+        if parent.get('retained_from_previous'):
+            record.update(retained_from_previous=True,latest_price_status='unavailable',observed_at=parent.get('observed_at'))
         cache[key]=record
         return record
     for key in nodes:visit(key,set())
@@ -69,31 +101,11 @@ def enrich(snapshot,market,folder,deadline=None):
     if recorded.get('market_pending'):raise MarketPause('Reserve checks reached the market time budget. Resume saved checks in Activity.')
     ordinary=[r for r in graph if r.get('address') and r.get('is_curve') is False and r['chain_id'] in ALCHEMY]
     prices=list(market.get('tokens',[]))
-    rejected={(p['chain_id'],p['address'].lower()) for p in prices if p.get('quality')=='unreliable'}
-    ordinary=[r for r in ordinary if (r['chain_id'],r['address'].lower()) not in rejected]
-    # Only reserve assets are requested. Identify prices by network and contract, never symbol.
-    requests=[{'network':ALCHEMY[r['chain_id']],'address':r['address']} for r in ordinary]
-    inverse={value:key for key,value in ALCHEMY.items()}
-    responses=[]
-    key=h.secrets().get('ALCHEMY_CUSTOM_APY_KEY')
-    for i in range(0,len(requests) if key else 0,25):
-        import hashlib
-        batch=requests[i:i+25];identity=hashlib.sha256(json.dumps(batch,sort_keys=True).encode()).hexdigest()
-        file=folder/('reserve-price-cache-'+identity+'.json')
-        record=json.loads(file.read_text()) if file.exists() else None
-        if not record:
-            response=fetch('https://api.g.alchemy.com/prices/v1/'+h.secrets()['ALCHEMY_CUSTOM_APY_KEY']+'/tokens/by-address',{'addresses':batch},deadline=deadline)
-            record={'observed_at':h.now(),'source':'Alchemy token prices by address','request':batch,'response':response}
-            if isinstance(response,dict) and isinstance(response.get('data'),list):atomic(file,record)
-        response=record['response'];responses.append(record)
-        for record in response.get('data') or []:
-            p=next((p for p in record.get('prices',[]) if p.get('currency')=='usd' and p.get('value') is not None),None)
-            if p and not record.get('error'):
-                value=float(p['value'])
-                if math.isfinite(value) and value>0:
-                    prices.append({'chain_id':inverse[record['network']],'address':record['address'],'usd':value,'basis':'Market index','quality':'estimated',
-                                   'observed_at':p.get('lastUpdatedAt'),'source':'https://www.alchemy.com/docs/data/prices-api/prices-api-endpoints/prices-api-endpoints/get-token-prices-by-address'})
-    atomic(folder/'reserve-market-prices.json',responses)
+    settled={(p['chain_id'],p['address'].lower()) for p in prices
+             if p.get('usd') is not None or p.get('quality') in ('unfunded','unreliable')}
+    ordinary=[r for r in ordinary if (r['chain_id'],r['address'].lower()) not in settled]
+    indexed=index_prices([(r['chain_id'],r['address']) for r in ordinary],folder,deadline)
+    prices.extend(indexed['tokens'])
     def get(row):
         chain=DEX.get(row['chain_id'])
         if not chain:return None

package/docs/AGENT_TOOLS.md

@@ -94,6 +94,10 @@ global skill directory. Follow that host's configuration and approval flow.
   `holdings_query` for full-inventory counts, aggregates and rankings instead
   of asking the model to total a truncated page. Query results are bounded to
   25 per page; wallet and historical holdings pages allow up to 100.
+- For price history, call `snapshots_list` with `kind: "prices"` (or `"all"`),
+  then use its IDs with `snapshot_read` and `snapshots_compare`. The default
+  remains holdings history. Each price observation uses its saved overlay and
+  linked holdings; later refreshes cannot replace those selected prices.
 - Report same-symbol ambiguity. Exact identities are chain ID plus contract,
   or `native` for a chain's native asset. Missing records are unknown, not zero.
 - `kira jobs wait ID --timeout 30 --json` waits up to the requested limit

package/docs/CLI.md

@@ -1,9 +1,9 @@
 # CLI and provider configuration
 
-Kira 0.2.2 is a local wallet engine, CLI and web interface. Any capable agent
+Kira is a local wallet engine, CLI and web interface. Any capable agent
 can use the CLI; MCP is optional. Your agent host supplies its own model,
 conversation, general tools and approvals. Kira does not start a model process.
-This branch prepares 0.2.2. Registry publication remains an operator action.
+Version 0.2.2 is published on npm. This source prepares 0.2.3.
 
 ## Install and choose a workspace
 
@@ -179,10 +179,18 @@ kira call holdings_query --arguments '{"mode":"search","query":"ETH"}' --json
 kira call wallet_read --arguments '{"wallet":"Daily wallet","offset":0,"limit":100}' --json
 kira call token_read --arguments '{"chain_id":8453,"address":"native"}' --json
 kira call snapshots_list --arguments '{"wallet":"Daily wallet","limit":20}' --json
+kira call snapshots_list --arguments '{"wallet":"Daily wallet","kind":"prices","limit":20}' --json
 kira call job_list --arguments '{"state":"active","offset":0,"limit":20}' --json
 kira ui context --json
 ```
 
+`snapshots_list` defaults to holdings analyses. Use `kind: "prices"` for saved
+price observations or `kind: "all"` for both. Pass the returned IDs to
+`snapshot_read` or `snapshots_compare`. Price observations reproduce their saved
+overlay and keep the linked holdings unchanged, even after another refresh.
+Comparisons include price/value changes and native positions; a price change
+is not a token transfer. No provider request is made by these reads.
+
 `job_list` accepts `state` groups `all` (default), `active` (queued or
 running), `succeeded` (succeeded or partial), `attention` (interrupted or
 failed) and `cancelled`, or one exact state: `queued`, `running`, `partial`,

package/docs/RELEASE.md

@@ -1,6 +1,36 @@
 # Release preparation
 
-## Prepared release: 0.2.2
+## Candidate 0.2.3
+
+Research and price refresh share the Alchemy index fallback and DEX liquidity
+checks. Insufficient or extremely one-sided DEX liquidity stays unpriced;
+provider gaps retain usable prior observations with their original timestamps.
+Cash-out classification uses the same DEX price validation as wallet valuation.
+The symbol-based MEMBER pool override is removed, and a failed curve network
+no longer discards observations from other networks.
+
+History tools accept `snapshots_list` with `kind: "prices"` or `"all"`.
+`snapshot_read` and `snapshots_compare` accept those immutable observation IDs,
+with linked holdings, native positions, independent timestamps and unknowns.
+Price-only refresh also saves evidence when run directly from Python.
+
+OWS registration retries recover the same admitted job after interrupted
+worker launch or receipt storage, including requests saved by 0.2.2. Previously
+registered wallets keep their names, and cancelled jobs remain cancelled.
+Unused embedded-agent completion parsing is removed. The website setup link
+points to the currently published 0.2.2 guide until the next site update.
+
+One independent review of the four audit PRs found a legacy OWS receipt recovery
+gap, corrected with an upgrade regression. Final verification covers the full
+suite, isolated installation, exact archive members, CLI/MCP price history and
+source/history privacy checks. Synthetic checks do not claim live provider or
+Gemini/Grok account acceptance.
+
+Freeze the final archive from the validated, landed source and dry-run that
+exact archive. Release publication and website deployment remain operator
+actions. Preparation does not establish registry publication.
+
+## Published 0.2.2
 
 Fixes two agent contract findings from the published 0.2.1 fresh-agent test.
 `job_list` now publishes its accepted `state` values in the tool schema and
@@ -26,9 +56,11 @@ The skill corrects `head_status`, notes the native `address: null`, the
 100-event job window and older settings receipts. Wallet records, research,
 financial projections and the web app are unchanged.
 
-Preserve the published 0.2.1 archive and every earlier archive. Freeze 0.2.2
-from the accepted clean commit with `scripts/prepare-release.py`, dry-run that
-exact archive and leave registry publication to the operator. Review not selected.
+The operator published 0.2.2 on 2026-10-25. It was frozen from the landed
+merge commit `4c15c69a7e7031a1f52e57d971927abe82fe85f8`. The registry archive is
+byte-identical to the frozen one, SHA-256
+`5d954fc1cb9e679d8f33c94f71721052315e589e4550540e8f5bda10e1ab5089`, and a fresh
+registry install matched all 93 members. Review not selected.
 
 ## Published 0.2.1
 
@@ -159,7 +191,7 @@ The earlier unpublished 0.1.2 candidate is preserved in the ignored
 `dist/preserved-0.1.2-bad8f02/` directory. Use the current `dist/release.json`
 and its matching archive for publication; do not mix manifests from candidates.
 
-Keep published GitHub tags, release assets and npm versions through 0.2.1
+Keep published GitHub tags, release assets and npm versions through 0.2.2
 immutable. Do not rebuild them from later documentation commits. Future package
 changes need a new version. Release preparation does not publish a GitHub
 release, promote the website or publish to npm.
@@ -175,12 +207,12 @@ python3 scripts/prepare-release.py
 ```
 
 `prepare-release.py` scans the package boundary and creates
-`dist/kira-wallet-0.2.2.tgz`. The ignored `dist/release.json` records its source
+`dist/kira-wallet-VERSION.tgz` for the version in `package.json`. The ignored `dist/release.json` records its source
 commit, SHA-256 and member count. It never publishes. After reviewing that
 manifest, the operator's final command from the project root is:
 
 ```sh
-npm publish ./dist/kira-wallet-0.2.2.tgz --access public
+npm publish ./dist/kira-wallet-VERSION.tgz --access public
 ```
 
 Use the operator's npm account and complete authentication or OTP personally.

package/kira_jobs.py

@@ -490,8 +490,21 @@ class JobStore:
         path = (self.root / snapshot_id).resolve()
         if not path.is_relative_to((self.root / 'snapshots').resolve()) or '..' in Path(snapshot_id).parts:
             raise JobError('invalid_snapshot', 'Snapshot ID is outside saved evidence.')
-        if not (path / 'results.json').is_file(): raise JobError('not_found', 'Snapshot was not found.')
-        result = read(path / 'results.json')
+        if (path / 'results.json').is_file():result = read(path / 'results.json')
+        elif (path / 'prices.json').is_file():
+            overlay=read(path/'prices.json')
+            source=overlay.get('snapshot_id')
+            if not isinstance(source,str) or not source.startswith('snapshots/') or '..' in Path(source).parts:
+                raise JobError('invalid_snapshot','Invalid holdings source for this price observation.')
+            holdings=(self.root/source/'results.json').resolve()
+            if not holdings.is_relative_to((self.root/'snapshots').resolve()) or not holdings.is_file():
+                raise JobError('invalid_snapshot','Price observations require a saved holdings source.')
+            result=read(holdings)
+            if overlay.get('wallet_address','').lower()!=result.get('wallet_address','').lower():
+                raise JobError('wallet_mismatch','Price observation and holdings must belong to the same wallet.')
+            result={**result,'price_observation':{'snapshot_id':snapshot_id,'holdings_snapshot':source,'observed_at':overlay.get('observed_at')},
+                    'price_overlay':{k:overlay[k] for k in ('observed_at','wallet_address','tokens','native_usd','markets','sell_quotes') if k in overlay}}
+        else:raise JobError('not_found', 'Snapshot was not found.')
         # Public readers receive financial facts, never arbitrary raw provider files.
         from kira_config import redact
         def safe(value, key=''):
@@ -510,8 +523,22 @@ class JobStore:
         from decimal import Decimal, InvalidOperation, localcontext
         old, new = self.snapshot(before), self.snapshot(after)
         if old['wallet_address'].lower() != new['wallet_address'].lower():raise JobError('wallet_mismatch','Choose snapshots from the same wallet.')
+        price_comparison=bool(old.get('price_observation') or new.get('price_observation'))
+        valuations=[]
+        if price_comparison:
+            sys.path.insert(0,str(ASSETS/'viewer'))
+            from model import project_wallet
+            entry=self.wallet(old['wallet_address'])
+            for identity,snapshot in ((before,old),(after,new)):
+                source=(snapshot.get('price_observation') or {}).get('holdings_snapshot',identity)
+                projected=project_wallet({**entry,'latest_snapshot':{'directory':source}},snapshot,self.root,market=snapshot.get('price_overlay'))
+                valuations.append({a['id']:a for a in projected['assets']})
         def positions(snapshot):
-            return {(t['chain_id'],t['token_address'].lower(),t.get('token_id')):t for t in snapshot.get('tokens',[])}
+            rows={(t['chain_id'],t['token_address'].lower(),t.get('token_id')):t for t in snapshot.get('tokens',[])}
+            if price_comparison:
+                rows.update({(c['chain_id'],'native',None):{'symbol':c.get('native_symbol'),'wallet_balance':c.get('native_balance')}
+                             for c in snapshot.get('coverage',[])})
+            return rows
         left,right=positions(old),positions(new);changes=[]
         for identity in sorted(left.keys() | right.keys(),key=str):
             a,b=left.get(identity),right.get(identity);delta=None
@@ -530,6 +557,13 @@ class JobStore:
                 'presence':'both' if a and b else 'new_record' if b else 'absent_record',
                 'price_references_changed':(a or {}).get('indexer_price_references')!=(b or {}).get('indexer_price_references'),
                 'valuation_method_changed':bool((a or {}).get('mintclub'))!=bool((b or {}).get('mintclub'))})
+            if price_comparison:
+                first,last=(values.get(str(identity[0])+':'+identity[1],{}) for values in valuations)
+                def price(asset):
+                    return {k:asset['price'].get(k) for k in ('usd','basis','quality','observed_at')} if asset.get('price') else None
+                changes[-1].update(before_price=price(first),after_price=price(last),
+                                   before_value_usd=first.get('value_usd'),after_value_usd=last.get('value_usd'),
+                                   price_references_changed=price(first)!=price(last))
         def counts(rows):
             return {'position_count':len(rows),
                 'new_record_count':sum(r['presence']=='new_record' for r in rows),
@@ -539,26 +573,36 @@ class JobStore:
                 'unchanged_observation_count':sum(r['balance_comparison']=='unchanged_observations' for r in rows),
                 'different_observation_count':sum(r['balance_comparison']=='different_observations' for r in rows),
                 'unknown_comparison_count':sum(r['balance_comparison']=='unknown' for r in rows)}
-        summary={'scope':'full_recorded_non_native_token_comparison_before_pagination',
+        summary={'scope':'full_recorded_price_comparison_before_pagination' if price_comparison else 'full_recorded_non_native_token_comparison_before_pagination',
             'totals':counts(changes),
             'chains':[{'chain_id':cid,**counts([r for r in changes if r['chain_id']==cid])}
                 for cid in sorted({r['chain_id'] for r in changes})]}
         return {'schema_version':1,'before':before,'after':after,'wallet':new['wallet_address'],
-            'coverage_changed':old.get('coverage')!=new.get('coverage'),'price_references_changed':old.get('price_references')!=new.get('price_references'),
-            'comparison_summary':summary,'positions':changes,'note':'Absent records are unknown, not zero. Missing prior or later observations cannot establish or rule out receipts, disposals or transfers. Broader discovery can explain visibility, but activity and its cause remain unknown without transfer history. Even equal observed balances do not exclude intervening activity. Price overlays have separate observations and are not balance changes. Coverage changes compare full evidence, including observation times and blocks; this alone does not prove the set of checked networks changed. Positions compare direct token records. Read both snapshots to compare native balances.'}
+            'coverage_changed':old.get('coverage')!=new.get('coverage'),'price_references_changed':old.get('price_references')!=new.get('price_references') or price_comparison and any(r['price_references_changed'] for r in changes),
+            'comparison_summary':summary,'positions':changes,'note':'Absent records are unknown, not zero. Missing prior or later observations cannot establish or rule out receipts, disposals or transfers. Broader discovery can explain visibility, but activity and its cause remain unknown without transfer history. Even equal observed balances do not exclude intervening activity. Price overlays have separate observations and are not balance changes. Coverage changes compare full evidence, including observation times and blocks; this alone does not prove the set of checked networks changed. ' + ('Positions include native assets and the selected recorded price observations.' if price_comparison else 'Positions compare direct token records. Read both snapshots to compare native balances.')}
 
-    def snapshots(self, wallet):
+    def snapshots(self, wallet, kind='holdings'):
+        if kind not in ('holdings','prices','all'):raise JobError('invalid_snapshot_kind','Choose holdings, prices or all.')
         key = self.wallet(wallet)['address_key']
         paths = {w['latest_snapshot']['directory'] for w in read(self.root / 'wallets.json')['wallets'] if w['address_key'] == key and w.get('latest_snapshot')}
         for run in read(self.root / 'wallets.json').get('research_runs', []):
             if run['address_key'] == key: paths.add(run['snapshot'])
         rows = []
-        for path in paths:
+        for path in paths if kind!='prices' else []:
             # phase "initial" marks progress published while a holdings lookup was still running.
             snapshot = self.snapshot(path)
             rows.append({'snapshot_id': path, 'compiled_at': snapshot.get('compiled_at'), 'status': snapshot.get('status'),
                          'phase': (snapshot.get('pipeline') or {}).get('phase')})
-        return sorted(rows, key=lambda r: r['compiled_at'] or '')
+        if kind!='holdings':
+            evidence=set((self.root/'snapshots/jobs').glob('*/prices.json'))
+            for path in paths:evidence.update((self.root/path/'price-evidence').glob('*/prices.json'))
+            for file in evidence:
+                if not file.resolve().is_relative_to((self.root/'snapshots').resolve()):continue
+                overlay=read(file)
+                if overlay.get('wallet_address','').lower()!=key or overlay.get('snapshot_id') not in paths:continue
+                rows.append({'snapshot_id':str(file.parent.relative_to(self.root)),'compiled_at':overlay.get('observed_at'),
+                             'status':overlay.get('job_result_status'),'phase':'prices','holdings_snapshot':overlay['snapshot_id']})
+        return sorted(rows, key=lambda r: (r['compiled_at'] or '',r['snapshot_id']))
 
     def publication(self, job):
         if job['operation'].startswith('settings.') or job['operation']=='wallet.setTags':

package/kira_ows.py

@@ -10,7 +10,7 @@ import shutil
 import subprocess
 import threading
 import uuid
-from kira_jobs import JobError, JobStore, atomic, fields, identifier
+from kira_jobs import JobError, JobStore, atomic, digest, fields, identifier
 
 class OwsStore:
     def __init__(self, root, vault=None, runner=None):
@@ -104,8 +104,14 @@ class OwsStore:
             address=wallet['accounts'][0]['address'];store=JobStore(self.root)
             registered=next((w for w in json.loads((self.root/'wallets.json').read_text())['wallets'] if w['address_key']==address.lower()),None)
             job=None
-            if not registered:
-                job=store.submit({'schema_version':1,'operation':'wallet.add','input':{'address':address,'tag':tag},'idempotency_key':str(uuid.uuid5(uuid.UUID(key),'ows-register'))})
+            registration_key=str(uuid.uuid5(uuid.UUID(key),'ows-register'))
+            # Pre-intent receipts from older versions may already own a queued job.
+            if not registered or receipt.get('registration_requested') or any(j['key_hash']==digest(registration_key) for j in store.list()):
+                # Record intent before admission: submit can register the wallet
+                # before this process has saved its job ID or started a worker.
+                if not receipt.get('registration_requested'):
+                    receipt['registration_requested']=True;atomic(path,receipt)
+                job=store.submit({'schema_version':1,'operation':'wallet.add','input':{'address':address,'tag':tag},'idempotency_key':registration_key})
                 if job['state']=='queued':store.launch()
             connection={'source':'ows','wallet_id':wallet['id'],'name':wallet['name'],'address':address,'tag':(registered.get('tags') or [tag])[0] if registered else tag}
             atomic(self.session,connection);self.session.chmod(0o600)

package/kira_records.py

@@ -4,166 +4,6 @@ import re
 from pathlib import Path
 from kira_jobs import JobError
 
-def read_receipt(name, arguments, result, delivered=True):
-    receipt={'name':name,'arguments':arguments,'status':'completed' if delivered and not (isinstance(result,dict) and result.get('error')) else 'failed'}
-    if name=='portfolio_read' and isinstance(result,dict) and isinstance(result.get('wallets'),list):
-        receipt['wallet_pages']=[read_receipt('inventory_page',{'wallet':w['address'],'offset':w.get('offset',0)},w,receipt['status']=='completed') for w in result['wallets']]
-    if name=='snapshot_read' and isinstance(result,dict) and isinstance(result.get('wallets'),list) and len(result['wallets'])==1:
-        receipt['snapshot_id']=result.get('snapshot_id')
-        result=result['wallets'][0]
-    if isinstance(result,dict):
-        for key in ('offset','next_offset','asset_count','position_count','snapshot_id','query_scope'):
-            if key in result:receipt[key]=result[key]
-        for key in ('assets','positions'):
-            if isinstance(result.get(key),list):receipt['page_end']=result.get('offset',0)+len(result[key])
-    return receipt
-
-def read_completion(message, receipts, tools):
-    """Validate declared plans and literal requests against delivered receipts."""
-    ranking=re.search(r'\btop[- ]*(\d+|one|two|three|four|five|ten)\b|상위\s*(\d+|다섯|열)',message,re.I)
-    requested_rank=None
-    if ranking:
-        raw=next(v for v in ranking.groups() if v).lower()
-        requested_rank=int(raw) if raw.isdigit() else {'one':1,'two':2,'three':3,'four':4,'five':5,'ten':10,'다섯':5,'열':10}[raw]
-    names=set(re.findall(r'\b(?:holdings_query|portfolio_read|wallet_read|snapshot_read|snapshots_compare|token_read|job_read|job_list|snapshots_list)\b',message))
-    literal_names=names.copy()
-    decoder=json.JSONDecoder();requested=[]
-    for match in re.finditer(r'\{',message):
-        try:value,_=decoder.raw_decode(message[match.start():])
-        except ValueError:continue
-        if isinstance(value,dict) and value.get('name',value.get('kira_tool')) in names and isinstance(value.get('arguments'),dict):
-            requested.append((value.get('name',value.get('kira_tool')),value['arguments']))
-    for receipt in receipts:
-        plan=receipt.get('arguments')
-        if receipt['name']=='records_read' and isinstance(plan,dict) and isinstance(plan.get('reads'),list):
-            for read in plan['reads']:
-                if isinstance(read,dict) and isinstance(read.get('name'),str) and isinstance(read.get('arguments'),dict):
-                    names.add(read['name']);requested.append((read['name'],read['arguments']))
-    if not requested_rank and (not names or not requested and not re.search(r'\b(?:read|call|run|use|execute)\b|읽|호출|실행|수행|\+',message,re.I)):return None
-    expanded=[]
-    for receipt in receipts:
-        expanded.extend(receipt.get('reads',[]) if receipt['name']=='records_read' else [receipt])
-    expanded.extend(page for r in list(expanded) for page in r.get('wallet_pages',[]))
-    completed=[r for r in expanded if r['status']=='completed']
-    missing=[name for name in sorted(names) if not any(r['name']==name for r in completed)]
-    if tools and 'wallet_read' in literal_names:
-        context,approved=tools.allowed()
-        wallets=context['wallets']
-        selected=wallets if re.search(r'\b(?:all|each|every)\b|모든|각각|전부',message,re.I) else [w for w in wallets if w['address'].lower() in message.lower() or any(tag.lower() in message.lower() for tag in w['tags'])]
-        actual=set()
-        for receipt in completed:
-            if receipt['name']=='wallet_read':
-                try:actual.add(tools.wallet(receipt['arguments']['wallet'],approved))
-                except JobError:pass
-        missing.extend('wallet_read '+w['name'] for w in selected if w['address'].lower() not in actual)
-    if 'snapshot_read' in names:
-        snapshot_requested=set(re.findall(r'snapshots/[A-Za-z0-9_./-]+',message))
-        actual={r['arguments'].get('snapshot_id') for r in completed if r['name']=='snapshot_read'}
-        missing.extend('snapshot_read '+identity for identity in sorted(snapshot_requested-actual))
-    # Literal JSON read plans are checked by argument, including chain identity.
-    # This is a bounded parser, not a claim to understand every natural request.
-    from kira_research_tools import CATALOG
-    specifications={row['name']:row for row in CATALOG}
-    specifications['inventory_page']={'arguments':{'wallet':None},'optional_arguments':{'offset':None}}
-    def matches(name,wanted,receipt):
-        if receipt['name']!=name:return False
-        if not isinstance(wanted,dict) or not isinstance(receipt.get('arguments'),dict):return False
-        spec=specifications.get(name)
-        if spec is None:return False
-        required=set(spec['arguments']);allowed=required|set(spec.get('optional_arguments',{}))
-        if any(not required<=set(args) or set(args)-allowed for args in (wanted,receipt['arguments'])):return False
-        defaults={'offset':0,'limit':100 if name=='wallet_read' else 20} if name in ('wallet_read','snapshot_read','snapshots_compare') else {}
-        if name=='inventory_page':defaults={'offset':0}
-        wanted={**defaults,**wanted};actual={**defaults,**receipt.get('arguments',{})}
-        if set(wanted)!=set(actual):return False
-        for key,value in wanted.items():
-            other=actual.get(key)
-            if key=='minimum_value_usd':
-                from decimal import Decimal, InvalidOperation
-                try:
-                    left,right=Decimal(str(value)),Decimal(str(other))
-                    if not left.is_finite() or not right.is_finite() or left!=right:return False
-                except InvalidOperation:return False
-                continue
-            if key=='wallet' and tools:
-                try:
-                    _,approved=tools.allowed();value=tools.wallet(value,approved);other=tools.wallet(other,approved)
-                except JobError:return False
-            if isinstance(value,str) and key in ('address','wallet'):value=value.lower();other=other.lower() if isinstance(other,str) else other
-            if type(value) is not type(other) or value!=other:return False
-        return True
-    # A delivered retry fulfils the same request. Keep failed attempts in the
-    # original receipts, but do not call a recovered request incomplete.
-    failed=[{'name':r['name'],'arguments':r.get('arguments',{})} for r in expanded
-            if r['status']=='failed' and r['name']!='inventory_page'
-            and not any(matches(r['name'],r.get('arguments',{}),ok) for ok in completed)]
-    missing.extend(name+' '+json.dumps(args,sort_keys=True) for name,args in requested if not any(matches(name,args,r) for r in completed))
-    if 'token_read' in names and not any(name=='token_read' for name,_ in requested):
-        addresses=set(re.findall(r'0x[0-9a-fA-F]{40}',message))
-        chains={int(value) for value in re.findall(r'\bchain(?:_id)?\s*[:=]?\s*(\d+)\b',message,re.I)}
-        for address in addresses:
-            relevant=[r for r in completed if r['name']=='token_read' and str(r['arguments'].get('address','')).lower()==address.lower()]
-            if not relevant:missing.append('token_read '+address)
-            for chain in chains:
-                if not any(r['arguments'].get('chain_id')==chain for r in relevant):missing.append('token_read '+str(chain)+':'+address)
-    unread=[]
-    exhaustive=bool(re.search(r'\b(?:complete|full)\s+inventory\b|\ball\s+(?:holdings|assets|positions)\b|전체\s*(?:보유|자산|목록)',message,re.I))
-    groups={}
-    for r in expanded:
-        if r['name'] not in ('wallet_read','snapshot_read','snapshots_compare','inventory_page','holdings_query'):continue
-        if r['name']=='holdings_query' and (r.get('query_scope') or {}).get('mode')!='search':continue
-        if not isinstance(r.get('arguments'),dict):continue
-        if r['status']=='failed' and any(matches(r['name'],r.get('arguments',{}),ok) for ok in completed):continue
-        if r['name']=='inventory_page' and not exhaustive:continue
-        identity={k:v for k,v in r['arguments'].items() if k not in ('offset','limit')}
-        if 'wallet' in identity and tools:
-            try:identity['wallet']=tools.wallet(identity['wallet'],tools.allowed()[1])
-            except JobError:pass
-        name='wallet_read' if r['name']=='inventory_page' else r['name']
-        groups.setdefault((name,json.dumps(identity,sort_keys=True),r.get('snapshot_id')),[]).append(r)
-    for (name,identity,snapshot),pages in groups.items():
-        offset=0;seen=set();finished=False
-        while offset not in seen:
-            seen.add(offset);page=next((r for r in pages if r['status']=='completed' and r['arguments'].get('offset',0)==offset and 'next_offset' in r),None)
-            if not page:break
-            if page['next_offset'] is None:finished=True;break
-            if type(page['next_offset']) is not int or page['next_offset']<=offset:break
-            offset=page['next_offset']
-        if not finished and (exhaustive or any(r.get('next_offset') is not None for r in pages)):
-            unread.append({'name':name,'arguments':{**json.loads(identity),'offset':offset},'snapshot_id':snapshot})
-    if requested_rank:
-        from decimal import Decimal
-        ranked=[r for r in completed if r['name']=='holdings_query' and (r.get('query_scope') or {}).get('mode')=='rank']
-        rank_pages={};approved_wallets=None
-        for r in ranked:
-            q=r['query_scope']
-            if not q.get('full_inventory_scanned') or not q.get('complete'):continue
-            identity={'environment':'mainnet','group_by':'asset','query':'',
-                      **{k:v for k,v in r['arguments'].items() if k not in ('offset','limit')}}
-            identity['query']=identity['query'].strip().casefold()
-            if 'minimum_value_usd' in identity:identity['minimum_value_usd']=Decimal(str(identity['minimum_value_usd']))
-            if 'wallet' in identity and tools:
-                try:
-                    if approved_wallets is None:approved_wallets=tools.allowed()[1]
-                    identity['wallet']=tools.wallet(identity['wallet'],approved_wallets)
-                except JobError:continue
-            rank_pages.setdefault((tuple(sorted(identity.items())),q['result_count']),[]).append(q)
-        rank_complete=False
-        for (_,available),pages in rank_pages.items():
-            covered=0
-            for page in sorted(pages,key=lambda q:q['offset']):
-                if page['offset']>covered:break
-                covered=max(covered,page['offset']+page['returned_count'])
-            if covered>=min(requested_rank,available):rank_complete=True;break
-        if not rank_complete:
-            missing.append('holdings_query rank for the requested top '+str(requested_rank))
-    for r in completed:
-        q=r.get('query_scope')
-        if q and not q.get('complete'):missing.append('holdings_query result detail was truncated')
-    missing.extend('holdings_query has unread matching records' for r in unread if r['name']=='holdings_query')
-    if exhaustive:missing.extend(r['name']+' unread offset '+str(r['arguments']['offset']) for r in unread)
-    return {'status':'partial' if missing or failed else 'complete','missing':list(dict.fromkeys(missing)),'failed':failed,'unread_pages':unread,'completed_reads':sum(r['name']!='inventory_page' for r in completed)}
-
 def scoped_wallets(root,config):
     import sys
     sys.path.insert(0,str(Path(__file__).resolve().parent/'viewer'))

package/kira_research_tools.py

@@ -11,7 +11,7 @@ CATALOG = [
     {'name':'wallet_read','arguments':{'wallet':'registered address or exact name'},'optional_arguments':{'offset':'nonnegative integer, default 0','limit':'integer 1 to 100, default 100'},'description':'Read a compact holdings page of one approved wallet. Follow next_offset until null for the complete recorded inventory. Use token_read for curve, market and exit details.'},
     {'name':'holdings_query','arguments':{'mode':'search, rank or aggregate'},'optional_arguments':{'query':'Token symbol, name, exact contract or native. Required for search. Use one query per token.','wallet':'Optional registered wallet name or address; omit for every approved wallet.','chain_id':'Optional positive chain ID','environment':'mainnet (default), testnet or all','group_by':'asset (default: sum priced positions by chain and contract) or position','minimum_value_usd':'Optional nonnegative USD minimum per position; unknowns excluded and counted.','offset':'nonnegative integer, default 0','limit':'integer 1 to 25, default 10'},'description':'Search names, rank top N or aggregate the ENTIRE approved saved inventory on the host. No inventory pagination or jobs needed. Returns exact counts, values, ambiguity and bounded detailed matches. Use search for symbol-only questions, rank for top-N questions and aggregate for counts or sums.'},
     {'name':'token_read','arguments':{'chain_id':'positive integer','address':'contract address or native'},'optional_arguments':{'minimum_value_usd':'Nonnegative USD number or decimal string. Filter by recorded mainnet value; unknowns stay separate.'},'description':'Read this asset across ALL approved wallets in one request, including saved native observations. Use the optional minimum for value-threshold questions and the exact returned position_count. No wallet inventory pagination is needed.'},
-    {'name':'snapshots_list','arguments':{'wallet':'registered address or exact name'},'description':'List past saved analyses for an approved wallet.'},
+    {'name':'snapshots_list','arguments':{'wallet':'registered address or exact name'},'optional_arguments':{'kind':'holdings (default), prices or all'},'description':'List saved holdings analyses or immutable price observations for an approved wallet.'},
     {'name':'snapshot_read','arguments':{'snapshot_id':'saved snapshot ID'},'optional_arguments':{'offset':'nonnegative integer, default 0','limit':'integer 1 to 100, default 20'},'description':'Read a compact page of historical evidence for an approved wallet.'},
     {'name':'snapshots_compare','arguments':{'before':'saved snapshot ID','after':'saved snapshot ID'},'optional_arguments':{'offset':'nonnegative integer, default 0','limit':'integer 1 to 100, default 20'},'description':'Compare a page of recorded positions of the same approved wallet.'},
     {'name':'job_list','arguments':{},'description':'Read research jobs only for approved wallets.'},
@@ -62,21 +62,22 @@ class ResearchTools:
 
     def snapshot(self, identity, approved, offset=0, limit=20):
         # Only published historical analyses listed for this scope may be read.
-        visible={row['snapshot_id'] for key in approved for row in self.store.snapshots(key)}
+        visible={row['snapshot_id'] for key in approved for row in self.store.snapshots(key,kind='all')}
         if identity not in visible:raise JobError('snapshot_scope','This analysis is outside the current conversation scope.')
         result=self.store.snapshot(identity)
         if result.get('wallet_address','').lower() not in approved:raise JobError('snapshot_scope','This analysis does not belong to the approved wallet.')
         from kira_records import wallet_facts, compact_wallet_facts, recorded_valuation
         from model import project_wallet
         entry=self.store.wallet(result['wallet_address'])
-        entry={**entry,'latest_snapshot':{'directory':identity}}
-        wallet=project_wallet(entry,result,self.root);count=len(wallet['assets'])
+        observation=result.get('price_observation')
+        entry={**entry,'latest_snapshot':{'directory':observation['holdings_snapshot'] if observation else identity}}
+        wallet=project_wallet(entry,result,self.root,market=result.get('price_overlay'));count=len(wallet['assets'])
         wallet['recorded_valuation']=recorded_valuation(wallet['assets'])
         wallet['assets']=wallet['assets'][offset:offset+limit]
         rows=compact_wallet_facts(wallet_facts([wallet],pool_budget=0))
         rows[0].update(asset_count=count,assets_omitted=count-len(wallet['assets']),offset=offset,
                        next_offset=offset+len(wallet['assets']) if offset+len(wallet['assets'])<count else None)
-        return {'snapshot_id':identity,'wallets':rows,'note':'Historical recorded evidence. Prices and balances retain their observation times; curve backing is not executable cash. Follow next_offset for more holdings.'}
+        return {'snapshot_id':identity,**({'price_observation':observation} if observation else {}),'wallets':rows,'note':'Historical recorded evidence. Prices and balances retain their observation times; curve backing is not executable cash. Follow next_offset for more holdings.'}
 
     def job(self, job, approved):
         if job['operation'] not in ('wallet.add','wallet.refresh','prices.refresh'):
@@ -159,7 +160,7 @@ class ResearchTools:
             return {'identity':identity,'positions':positions,'position_count':len(positions),'unfiltered_position_count':total,
                     'unpriced_position_count':unpriced,'outside_usd_scope_count':outside,'curve_comparison':compare_curve_states(positions),
                     'note':'An absent record is unknown, not a verified zero holding.'}
-        if name=='snapshots_list':return self.store.snapshots(self.wallet(arguments['wallet'],approved))
+        if name=='snapshots_list':return self.store.snapshots(self.wallet(arguments['wallet'],approved),arguments.get('kind','holdings'))
         if name=='snapshot_read':return self.snapshot(arguments['snapshot_id'],approved,arguments.get('offset',0),arguments.get('limit',20))
         if name=='snapshots_compare':
             self.snapshot(arguments['before'],approved);self.snapshot(arguments['after'],approved)

package/kira_service.py

@@ -18,6 +18,7 @@ for row in CATALOG:
         schema={'type':'integer','minimum':1 if name in ('chain_id','limit') else 0} if name in ('chain_id','offset','limit') else dict(STRING)
         if name=='minimum_value_usd':schema={'type':['string','number']}
         if name=='limit':schema['maximum']=25 if row['name']=='holdings_query' else 100
+        if row['name']=='snapshots_list' and name=='kind':schema['enum']=['holdings','prices','all']
         properties[name]={**schema,'description':description}
     if row['name'] in ('portfolio_read','job_list','snapshots_list'):
         properties.update(offset=INTEGER,limit={'type':'integer','minimum':1,'maximum':100})
@@ -128,7 +129,7 @@ class Application:
             return {'schema_version':1,'dashboard':state['dashboard'],**page(rows,offset,limit,key='wallets'),
                     'data_revision':self.views.revision,'note':'Saved summaries only. Use wallet_read for holdings pages and holdings_query for search, ranking and aggregates.'}
         if name=='snapshots_list':
-            return page(self.jobs.snapshots(arguments['wallet']),arguments.get('offset',0),arguments.get('limit',100),key='snapshots')
+            return page(self.jobs.snapshots(arguments['wallet'],arguments.get('kind','holdings')),arguments.get('offset',0),arguments.get('limit',100),key='snapshots')
         return self.records.call(name,arguments,str(uuid.uuid4()))
 
     def select(self,value):

package/market_records.py

@@ -1,5 +1,7 @@
 """Market identity and public routes. Pool existence never establishes a price."""
+from decimal import Decimal, InvalidOperation
 import json
+import math
 from pathlib import Path
 import re
 from urllib.parse import quote, urlsplit
@@ -9,6 +11,29 @@ NETWORKS={n['chain_id']:n['network'] for n in json.loads((Path(__file__).parent/
 UNISWAP_CHAINS={1:'ethereum',10:'optimism',56:'bnb',137:'polygon',8453:'base',42161:'arbitrum',43114:'avalanche',81457:'blast',130:'unichain',7777777:'zora',4663:'robinhood'}
 
 
+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
+
+MIN_PRICE_LIQUIDITY_USD=1000
+
+def checked_price(price, pools=()):
+    """A spot quote needs a meaningful observed market, including saved quotes."""
+    if not price or price.get('basis')!='DEX market':return price
+    liquidity=number(price.get('liquidity_usd'))
+    if liquidity is None:
+        pool=next((p for p in pools if p.get('source_url')==price.get('source')),None)
+        liquidity=number((pool.get('reported_liquidity') or {}).get('usd')) if pool else None
+        base=number((pool.get('reported_liquidity') or {}).get('base')) if pool else None
+        usd=number(price.get('usd'))
+        if liquidity and base is not None and usd is not None and base*usd/liquidity>0.98:
+            return {**price,'usd':None,'quality':'unreliable','basis':'Insufficient market liquidity','liquidity_usd':liquidity}
+    if liquidity is None or liquidity<MIN_PRICE_LIQUIDITY_USD:
+        return {**price,'usd':None,'quality':'unreliable','basis':'Insufficient market liquidity','liquidity_usd':liquidity}
+    return {**price,'liquidity_usd':liquidity}
+
 def market_url(chain_id, pool):
     """Choose a known venue route without changing the recorded data source."""
     venue=str(pool.get('venue','')).lower()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kira-wallet",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Local wallet research for your agent session and a human-controlled web workspace.",
   "license": "MIT",
   "private": false,
@@ -104,7 +104,7 @@
     "skills/kira-wallet"
   ],
   "scripts": {
-    "test": "python3 -m unittest discover -s . -p 'test_*.py' && python3 -m unittest discover -s viewer -p 'test_*.py' && node test-onchain.cjs && node test-onchain-continuation.cjs && node test-asset-review.cjs && node test-cashout-quotes.cjs && node test-cashout-routes.cjs && node --check viewer/static/app.js && node --check viewer/static/jobs.js && node test-workspace.cjs && node test-scan-ux.cjs && node --check viewer/static/workspace.js && node --check viewer/static/workspace-model.js && node test-watching.cjs && node test-watching-ui.cjs && node --check viewer/static/watching.js && node --check viewer/static/watching-model.js && node --check viewer/static/report.js && node test-report-ui.cjs && node test-holdings-ui.cjs && node test-settings-ui.cjs && node test-rpc-fallback.cjs && node test-ows.cjs && node test-ows-ui.cjs && node --check viewer/static/ows.js && node --check viewer/static/selects.js && node --check site/demo.js && node test-rpc-pool.cjs && node test-zero-verification.cjs && node test-market-discovery.cjs && node test-sell-quotes.cjs && node test-external-ui.cjs"
+    "test": "python3 -m unittest discover -s . -p 'test_*.py' && python3 -m unittest discover -s viewer -p 'test_*.py' && node test-onchain.cjs && node test-onchain-continuation.cjs && node test-asset-review.cjs && node test-cashout-quotes.cjs && node test-cashout-routes.cjs && node --check viewer/static/app.js && node --check viewer/static/jobs.js && node test-workspace.cjs && node test-scan-ux.cjs && node --check viewer/static/workspace.js && node --check viewer/static/workspace-model.js && node test-watching.cjs && node test-watching-ui.cjs && node --check viewer/static/watching.js && node --check viewer/static/watching-model.js && node --check viewer/static/report.js && node test-report-ui.cjs && node test-holdings-ui.cjs && node test-settings-ui.cjs && node test-rpc-fallback.cjs && node test-ows.cjs && node test-ows-ui.cjs && node --check viewer/static/ows.js && node --check viewer/static/selects.js && node --check site/demo.js && node test-rpc-pool.cjs && node test-zero-verification.cjs && node test-market-discovery.cjs && node test-sell-quotes.cjs && node test-external-ui.cjs && node test-refresh-curve-prices.cjs"
   },
   "dependencies": {
     "viem": "2.57.2"

package/sell_quotes.py

@@ -68,7 +68,7 @@ def candidates(snapshot, market):
             if len(pair) != 2 or address not in pair:
                 continue
             price = output_price(token['chain_id'], next(iter(pair - {address})), market)
-            if not price or price['basis'] == 'DEX market' and (decimal(price.get('liquidity_usd')) or 0) < 1000:
+            if not price:
                 continue
             pools.append(pool)
         if not pools:

package/skills/kira-wallet/SKILL.md

@@ -103,8 +103,11 @@ kira ui context --json
   compare `holdings` rows to see change between lookups.
 - A price refresh updates the prices shown for the latest snapshot, including
   through `snapshot_read`. `snapshot_price_references` keep the native prices
-  recorded by the holdings lookup. Earlier price observations remain local job
-  evidence but are not listed by the history tools.
+  recorded by the holdings lookup. To read immutable price history instead,
+  call `snapshots_list` with `kind: "prices"` or `"all"`, then use the returned
+  IDs with `snapshot_read` or `snapshots_compare`. These observations pair their
+  saved prices with the linked holdings and include native positions in price
+  comparisons. Default `kind: "holdings"` preserves the existing holdings list.
 - Per-position `price.usd` and `value_usd` are JSON numbers. Totals from
   `holdings_query` and `recorded_valuation` are exact decimal strings; use them
   instead of re-adding rounded position values. Check `price.observed_at`:

package/viewer/model.py

@@ -5,7 +5,6 @@ from decimal import Decimal, InvalidOperation, localcontext
 from pathlib import Path
 import hashlib
 import json
-import math
 import os
 import re
 from token_images import image_for, read_catalog, safe_image
@@ -13,7 +12,7 @@ from chain_images import chain_image
 from native_assets import native_identity
 from details import project_details
 from sell_quotes import classify_with_cache as cashout_classification
-from market_records import canonical_token, canonical_source, merge_pools, market_url
+from market_records import canonical_token, canonical_source, merge_pools, market_url, number, checked_price, MIN_PRICE_LIQUIDITY_USD
 
 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',
@@ -26,12 +25,6 @@ EXPLORERS = {1:'https://etherscan.io',8453:'https://basescan.org',81457:'https:/
     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 safe_routes(routes):
     result=[]
     if not isinstance(routes,list):return result
@@ -114,23 +107,6 @@ def sell_out_estimate(quote, eligibility, reserve_price):
     return {**quote, 'value_usd': value, 'valuation': 'reserve_reference',
             'output_price': price if usable else None, 'execution_verified': False}
 
-MIN_PRICE_LIQUIDITY_USD=1000
-
-def checked_price(price, pools=()):
-    """A spot quote needs a meaningful observed market, including saved quotes."""
-    if not price or price.get('basis')!='DEX market':return price
-    liquidity=number(price.get('liquidity_usd'))
-    if liquidity is None:
-        pool=next((p for p in pools if p.get('source_url')==price.get('source')),None)
-        liquidity=number((pool.get('reported_liquidity') or {}).get('usd')) if pool else None
-        base=number((pool.get('reported_liquidity') or {}).get('base')) if pool else None
-        usd=number(price.get('usd'))
-        if liquidity and base is not None and usd is not None and base*usd/liquidity>0.98:
-            return {**price,'usd':None,'quality':'unreliable','basis':'Insufficient market liquidity','liquidity_usd':liquidity}
-    if liquidity is None or liquidity<MIN_PRICE_LIQUIDITY_USD:
-        return {**price,'usd':None,'quality':'unreliable','basis':'Insufficient market liquidity','liquidity_usd':liquidity}
-    return {**price,'liquidity_usd':liquidity}
-
 def dex_price(token, observed):
     """Use the selected source observation, never a later publication clock.
 
@@ -161,13 +137,13 @@ def dex_price(token, observed):
             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):
+def project_wallet(entry, snapshot, root=ROOT, images=None, *, market=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'))
     all_networks=snapshot.get('pipeline',{}).get('phase') in ('holdings','sell') or snapshot.get('pipeline',{}).get('holdings_scope')=='all_configured'
     market_path=snapshot_dir/'market-prices.json'
-    market=read(market_path) if market_path.exists() else {}
+    market=(read(market_path) if market_path.exists() else {}) if market is None else market
     prices={(p.get('chain_id',8453),p['address'].lower()):p for p in market.get('tokens',[])}
     recorded_markets={p['id']:p.get('pools',[]) for p in market.get('markets',[])}
     legacy_pools={}

package/viewer/refresh-curve-prices.cjs

@@ -1,36 +1,26 @@
 const fs=require('fs');
 const h=require('../onchain.cjs');
-const {calls}=require('../pipeline-onchain.cjs');
-const file=process.argv[2];
-(async()=>{
- const snapshot=JSON.parse(fs.readFileSync(file));
+const pipeline=require('../pipeline-onchain.cjs');
+async function collect(snapshot){
  const allRows=snapshot.tokens.filter(t=>t.mintclub);
- const output=[];
+ const output=[],errors=[];
  const blocks={};
  for(const chainId of [...new Set(allRows.map(t=>t.chain_id))]){
+ try{
  const rows=allRows.filter(t=>t.chain_id===chainId);
  const c=await h.connect(chainId),block=(await h.snapshotBlock(c)).number;blocks[chainId]=block.toString();
  for(let i=0;i<rows.length;i+=8){
   const batch=rows.slice(i,i+8);
-  const res=await calls(c,batch.map(t=>({address:t.mintclub.bond_address,abi:h.bondAbi,functionName:'getDetail',args:[t.token_address]})),block);
+  const res=await pipeline.calls(c,batch.map(t=>({address:t.mintclub.bond_address,abi:h.bondAbi,functionName:'getDetail',args:[t.token_address]})),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_token:v.reserveToken,reserve_symbol:v.reserveSymbol,funded:v.reserveBalance>0n,source:require('../market-links.cjs').mintclubUrl(chainId,batch[j].symbol,batch[j].token_type||'ERC20'),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)});
   });
  }
+ }catch(error){errors.push({chain_id:chainId,error:h.safeError(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 h.snapshotBlock(c)).number;
-  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;});
+ return {observed_at:new Date().toISOString(),blocks,tokens:output,errors};
+}
+if(require.main===module)collect(JSON.parse(fs.readFileSync(process.argv[2])))
+ .then(result=>console.log(h.serialize(result))).catch(e=>{console.log(h.serialize(h.safeError(e)));process.exitCode=1;});
+module.exports={collect};

package/viewer/refresh_prices.py

@@ -11,12 +11,12 @@ import sys
 sys.path.insert(0,str(Path(__file__).resolve().parents[1]))
 import research as h
 from model import dex_price, within, number
-from curve_pricing import enrich, resolve
+from curve_pricing import enrich, resolve, index_prices
 from native_assets import market_metadata
 from market_records import collected_markets, canonical_token
 from chain_lifecycle import retired
 from token_images import refresh_catalog
-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'}
+from wallet import DEX as DEX_CHAINS, retain_price_evidence
 
 parser=argparse.ArgumentParser();parser.add_argument('--wallet',help='Registered wallet address or tag. Omit to refresh all registered snapshots.')
 args=parser.parse_args()
@@ -59,10 +59,10 @@ for w in selected:
   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))
+ with ThreadPoolExecutor(max_workers=5) as executor:fetched=list(executor.map(get,requests))
  pairs=[]
  for r in fetched:
-  response=r['response'];pairs.extend(response if isinstance(response,list) else response.get('pairs') or [])
+  response=r['response'];pairs.extend(response if isinstance(response,list) else (response.get('pairs') or []) if isinstance(response,dict) else [])
  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()]
@@ -76,6 +76,12 @@ for w in selected:
    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})
+ priced={(p['chain_id'],p['address'].lower()) for p in prices}
+ mainnets={c['chain_id'] for c in snapshot.get('coverage',[]) if c.get('environment')=='mainnet'}
+ indexed=index_prices([(t['chain_id'],t['token_address']) for t in snapshot['tokens']
+                       if t['chain_id'] in mainnets and t.get('token_type','ERC20')=='ERC20' and not t.get('mintclub')
+                       and (t['chain_id'],t['token_address'].lower()) not in priced],evidence_folder)
+ prices.extend(indexed['tokens'])
  curve_input=evidence_folder/'curve-refresh-input.json';h.save(curve_input,snapshot)
  try:node=subprocess.run(['node',str(Path(__file__).with_name('refresh-curve-prices.cjs')),str(curve_input)],capture_output=True,text=True,timeout=180)
  except subprocess.TimeoutExpired:rpc={'tokens':[],'errors':[{'code':'curve_budget','message':'Fresh curve checks reached their bound. Previous usable quotes are retained.'}]}
@@ -142,38 +148,33 @@ for w in selected:
     output['tokens']=list(partial.values())
  # Preserve historical quotes on a provider gap, after fresh reserve derivation.
  # Fresh unfunded/unreliable evidence must invalidate an old estimate.
- published={(p['chain_id'],p['address'].lower()):p for p in output['tokens']}
- retained=0
- for p in previous_market.get('tokens',[]):
-  key=(p['chain_id'],p['address'].lower());current=published.get(key)
-  if number(p.get('usd')) is None or p.get('quality') in ('unfunded','unreliable'):continue
-  if current and (number(current.get('usd')) is not None or current.get('quality') in ('unfunded','unreliable')):continue
-  published[key]={**p,'retained_from_previous':True};retained+=1
- output['tokens']=list(published.values());output['retained_price_records']=retained
+ output=retain_price_evidence(output,previous_market)
+ retained=sum(bool(p.get('retained_from_previous')) for p in output['tokens'])
+ output['retained_price_records']=retained
  if retained:output['note']+=f' {retained} token price references retain their earlier observation times because fresh USD was unavailable.'
  from sell_quotes import enrich as enrich_sell_quotes
  output=enrich_sell_quotes(snapshot,output,evidence_folder/'sell-quotes',previous=previous_market)
  try:refresh_catalog([snapshot],h.ROOT,native_images=native_market['images'],market_metadata=fetched)
  except (OSError,ValueError):output['image_refresh_status']='unavailable'
- 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').resolve()):raise ValueError('Job path must be within snapshots/.')
-  overlay=job_folder/'prices.json'
-  output['snapshot_id']=w['latest_snapshot']['directory']
-  missing_native=any(c.get('environment')=='mainnet' and float(c.get('native_balance') or 0)>0 and c.get('native_symbol')+'_USD' not in fresh_native for c in snapshot.get('coverage',[]))
-  # Name each gap so a partial price job explains itself.
-  output['job_result_gaps']=[name for name,found in (
-      ('market_discovery_partial',output.get('market_discovery_status')=='partial'),
-      ('native_price_missing',missing_native),
-      ('earlier_prices_retained',bool(retained)),
-      ('reserve_pricing_partial',output.get('reserve_price_status')=='partial' or bool((output.get('reserve_price_graph') or {}).get('errors'))),
-      ('curve_reads_incomplete',bool(rpc.get('errors')) or any('error' in p for p in rpc['tokens'])),
-      ('provider_request_failed',any(isinstance(r['response'],dict) and 'transport_error' in r['response'] for r in fetched))) if found]
-  output['job_result_status']='completed_with_coverage_gaps' if output['job_result_gaps'] 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']})
+ from kira_jobs import atomic
+ job_folder=evidence_folder.resolve()
+ if not job_folder.is_relative_to((h.ROOT/'snapshots').resolve()):raise ValueError('Job path must be within snapshots/.')
+ overlay=job_folder/'prices.json'
+ output['snapshot_id']=w['latest_snapshot']['directory']
+ missing_native=any(c.get('environment')=='mainnet' and float(c.get('native_balance') or 0)>0 and c.get('native_symbol')+'_USD' not in fresh_native for c in snapshot.get('coverage',[]))
+ # Name each gap so a partial price job explains itself.
+ output['job_result_gaps']=[name for name,found in (
+     ('market_discovery_partial',output.get('market_discovery_status')=='partial'),
+     ('native_price_missing',missing_native),
+     ('earlier_prices_retained',bool(retained)),
+     ('index_price_missing',indexed['status']=='partial'),
+     ('reserve_pricing_partial',output.get('reserve_price_status')=='partial' or bool((output.get('reserve_price_graph') or {}).get('errors'))),
+     ('curve_reads_incomplete',bool(rpc.get('errors')) or any('error' in p for p in rpc['tokens'])),
+     ('provider_request_failed',any(isinstance(r['response'],dict) and 'transport_error' in r['response'] for r in fetched))) if found]
+ output['job_result_status']='completed_with_coverage_gaps' if output['job_result_gaps'] else 'completed'
+ atomic(overlay,output)
+ if os.environ.get('KIRA_JOB_SNAPSHOT'):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)}))