kira-wallet 0.1.8 → 0.1.9

package/docs/FREE_RPC.md

@@ -7,7 +7,10 @@ effort and can throttle requests or omit historical state.
 The reviewed default catalog adds alternatives on Ethereum, Base, BNB Chain,
 Polygon, Arbitrum and Optimism. PublicNode is the initial preference. Reserves
 are selected per chain rather than downloaded from an untrusted runtime list.
-The other supported networks retain their existing endpoints.
+Shibarium and Puppynet use the current official Shib endpoints. Cyber mainnet
+adds the official Superchain registry endpoint. Unverified replacements are
+never accepted just because an endpoint returns HTTP 200. Some configured
+networks can remain unavailable; their missing balances stay unknown.
 
 ## Request behavior
 
@@ -110,3 +113,34 @@ Primary references: [EIP-1898](https://eips.ethereum.org/EIPS/eip-1898),
 [Circle contracts](https://developers.circle.com/stablecoins/usdc-contract-addresses),
 [Tether contracts](https://tether.to/en/supported-protocols/),
 [Uniswap Arbitrum deployments](https://developers.uniswap.org/docs/protocols/v3/deployments/v3-arbitrum-deployments).
+
+## Recorded route evidence and remaining limits
+
+Chain coverage includes `rpc_routes`: bounded aggregate logical endpoint outcomes
+with public/custom class, endpoint index, method, outcome and count. Failures
+can include HTTP or RPC error codes. A successful read can follow failed public
+attempts; configuring public first does not prove every read was public.
+Cooldown skips, queue timeouts and successes are distinct. The receipt contains
+no endpoint URLs, keys, request arguments or balances. Cached checkpoints retain
+their original evidence and routes; a resume is not a fresh observation.
+
+A live October 10 check identified DNS failures on the old Shib endpoints,
+Ham, Over and Cyber testnet. Current official Shib endpoints returned the correct
+chain identities and supported hash-qualified balance reads. Cyber mainnet's
+registry endpoint also passed. The official Cyber testnet replacement failed
+certificate validation, so it was not added. Ham and Over have no verified
+replacement in this catalog. This is an observation, not a claim that their
+chains permanently stopped. Their failed checks remain visible.
+
+Base public balance reads work independently of arbitrary token discovery.
+The keyless Base inventory remains selected common contracts and Mint Club.
+Blockscout's current documentation deprecates per-instance APIs in favor of its
+keyed PRO API. Kira does not promise keyless Base enumeration through that route.
+The former 1RPC Base reserve returned HTTP 410 during block lookup and was
+removed. PublicNode and dRPC remain verified Base candidates. The official Base
+public endpoint returned HTTP 403 in this test and was not silently substituted.
+
+Sources: [Shib network setup](https://docs.shib.io/get-started/deploy-contracts),
+[Superchain registry](https://github.com/ethereum-optimism/superchain-registry/blob/main/chainList.toml),
+[Ham network information](https://docs.ham.fun/docs/network-information/),
+[Blockscout API migration](https://docs.blockscout.com/devs/apis).

package/docs/ONBOARDING_CHAT_CONTRACT.md

@@ -98,3 +98,26 @@ native default-model response checks with no wallet data. The provider save
 used a synthetic local key reference and made no provider research request.
 Real extension approval, personal OWS passphrases and live holdings coverage
 are separate operator acceptance. Published 0.1.4 snapshots are not rewritten.
+
+## Recorded value and history interpretation
+
+`recorded_valuation` summarizes the full recorded mainnet inventory before any
+holdings pagination. Native, Mint Club and other-token categories are disjoint.
+Compact pages retain `exit_quote_recorded` when quote outputs are deferred.
+A true flag requires reading the token details before judging the historical
+quote. A false flag describes this snapshot, not the existence of an exit route.
+Each category carries its own priced-position count and price observation range.
+The all-priced total includes all three categories; it is never a Mint Club-only
+denominator. Missing category prices remain null. Spot sums at separate, possibly
+stale or indicative price times are not floors on current wealth or sale proceeds.
+
+Snapshot comparisons state whether both quantities were observed. Missing earlier
+or later quantities cannot establish or rule out receipts or disposals. Wider
+discovery can explain newly visible records; causal history remains unknown.
+Even equal endpoint quantities do not exclude intervening transfers. These facts
+and rules reach both supported native providers. Generated prose is not rewritten
+by keyword filters, so actual response quality still needs scoped verification.
+`comparison_summary` supplies exact full-comparison counts by chain before
+pagination. Missing earlier quantities, missing later quantities, equal and
+different observations stay separate. These counts cover recorded non-native
+token identities; they do not count native balances or infer transfer activity.

package/docs/RELEASE.md

@@ -94,12 +94,12 @@ python3 scripts/prepare-release.py
 ```
 
 `prepare-release.py` scans the package boundary and creates
-`dist/kira-wallet-0.1.8.tgz`. The ignored `dist/release.json` records its source
+`dist/kira-wallet-0.1.9.tgz`. 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.1.8.tgz --access public
+npm publish ./dist/kira-wallet-0.1.9.tgz --access public
 ```
 
 Use the operator's npm account and complete authentication or OTP personally.
@@ -123,9 +123,9 @@ with untouched settings fields while preserving edited drafts.
 
 The operator published **0.1.7** on October 9, 2026. Its archive is immutable.
 
-## Proposed 0.1.8 behavior
+## Published 0.1.8 behavior
 
-The next archive is **0.1.8**, unpublished until the operator runs the command.
+The operator published **0.1.8** on October 9, 2026. Its archive is immutable.
 It queues local connection imports during research, lets settings and price
 updates preempt enrichment, preserves explicit cancellation, and checkpoints
 wallet balance batches and market verification at fixed blocks. A 180-second
@@ -169,3 +169,27 @@ establish that native extension acceptance passed. Those actions still require
 the operator's device handoff. Signing and trading remain outside Kira. Human-submitted OWS creation stores an encrypted wallet in the separate local OWS vault.
 
 See [current UI evidence](https://github.com/realproject7/kira-wallet/blob/codex/kira-release/docs/KIRA_UI_REFINEMENT.md).
+
+## Proposed 0.1.9 behavior
+
+Version 0.1.9 permits a saved report's price update during detailed research,
+with duplicate queued/running price feedback and existing automatic continuation.
+Network empty states distinguish pending coverage, incomplete checks, completed
+empty records and actual filter exclusion. Native facts include full-inventory
+category valuation and explicit unknown activity causes. Public RPC configuration
+updates verified Shib/Cyber routes and removes a failed Base reserve. Sanitized
+route outcomes distinguish public-only acceptance from custom fallback. Bounded
+route telemetry retains aggregate outcomes when detailed records reach their cap.
+Compact agent facts retain historical quote presence even when outputs are deferred.
+Snapshot comparisons provide exact full-comparison and per-chain counts before
+pagination so native agents do not need to tally large position pages manually.
+
+Publication remains an operator action. Post-publication acceptance uses two
+clean installations of the same verified registry bytes: public/free only first,
+then a clean reinstall with authorized Alchemy discovery and public-first backup.
+Each lane begins without previous holdings, identity caches or RPC health.
+Compare exact chain/contract identities, observations, coverage, route classes,
+failures and runtime. Separate changed observation times from discovery effects.
+The procedure does not treat partial free discovery as exhaustive or stale spot
+sums as wealth floors. Private wallets, financial screenshots and local tickets
+stay outside the package and public review.

package/kira_agent.py

@@ -30,6 +30,7 @@ SYSTEM = ('You are Kira, a careful wallet research partner. Answer in the langua
     'A bounded summary is not contradictory new evidence. pools_omitted means recorded pool details were left out of this response, not absent from the record. '
     'Use token_read before judging or retracting market details when pools are omitted. Testnet assets are excluded from portfolio valuation; do not infer a zero market price. '
     'assets_omitted and next_offset describe a page, not missing holdings. Use wallet_read with offset and limit for more holdings, and token_read for detailed evidence. '
+    'Compact pages defer exit_quote and curve details. exit_quote_recorded true means a validated historical quote exists in the record even if its output is omitted here. Use token_read before judging execution evidence or claiming that a quote is absent. False means no validated quote in this snapshot, not that no exit route exists. '
     'For a complete inventory or portfolio comparison, follow next_offset for each approved wallet using limit 100. If the tool budget prevents this, state which pages remain unread. Inventory pages defer curve and exit details to token_read. '
     'rpc_pending or rpc_status pending means research has not reached that network. It is not an RPC outage. Only an explicit unavailable status proves a failed RPC check. '
     'Compare curve state only for the same chain and contract using comparable reserve, supply, next-mint price and royalty fields. A newer block or different wallet-sized burn output alone does not prove the curve moved. If comparable fields are unchanged, say no change was demonstrated; if missing, say the comparison is unknown. '
@@ -49,6 +50,10 @@ SYSTEM = ('You are Kira, a careful wallet research partner. Answer in the langua
     'In normalized wallet facts, chain complete means general ERC20 discovery was checked. In job chains, status complete means an on-chain checkpoint finished. These are different stages. Neither flag alone proves all holdings are known. registry_complete and candidate_balance_errors describe separate read coverage. An indexer check and unavailable RPC are separate coverage facts, not conflicting records. '
     'An explicit chains.native_balance of zero is an observed native balance at its recorded time and block; null is unknown. Empty positive-holding inventories do not erase these observations. '
     'For saved-analysis comparisons, use snapshots_compare and read both snapshots. coverage_changed compares full evidence, including times and blocks, not just network status flags. price_references_changed may include changed reference values or times, not balances. '
+    'comparison_summary gives exact full-comparison totals and per-chain counts before pagination. Use these counts instead of manually counting position pages. It covers recorded non-native tokens, not native balances, transfer history or unobserved discovery candidates. '
+    'A newly visible or absent token record is not a receipt or disposal. If either balance observation is missing, the change and its cause are unknown. Broader discovery can explain visibility but cannot establish or rule out receipts, transfers or intervening activity. Even equal observed balances do not prove no intervening transfers. '
+    'recorded_valuation covers all recorded mainnet positions of a wallet, including positions omitted from this page. Its all_priced_positions total includes native assets, Mint Club assets and other priced tokens. Use the exact category total and denominator for category exposure or concentration, never relabel a whole-wallet sum as Mint Club exposure. '
+    'These are estimated recorded priced subsets at their separate price observation times. Missing prices, stale prices and indicative curve spot prices mean the sum is not a floor, minimum wealth, lower bound on current value or guaranteed sale proceeds. Do not sum independent burn quotes as cash proceeds. '
     'Snapshot reads are normalized evidence. Compare chain observations and snapshot_price_references; never claim these are the only raw fields that changed. '
     'Your personality is a sharp, composed crypto analyst: concise, quietly confident, practical and a little dry. '
     'Talk like a knowledgeable person sitting beside the user. Lead with the actual finding or decision. '
@@ -115,6 +120,7 @@ def projection(root, config, *, token_id=None, limit=12, offset=0, wallet_key=No
     if config['scope'] == 'wallet':
         wallets = [w for w in wallets if w['key'] == config['wallet']]
         if len(wallets) != 1: raise JobError('wallet_missing','The approved wallet is no longer registered. Review your context settings.')
+    wallets=[{**w,'recorded_valuation':recorded_valuation(w['assets'])} for w in wallets]
     if token_id is not None:
         wallets=[{**wallet,'assets':[a for a in wallet['assets'] if a['id']==token_id]} for wallet in wallets]
     if wallet_key is not None: wallets=[w for w in wallets if w['key']==wallet_key]
@@ -141,17 +147,43 @@ def projection(root, config, *, token_id=None, limit=12, offset=0, wallet_key=No
     return result
 
 def compact_wallet_facts(rows):
-    asset_fields=('id','chain_id','address','symbol','name','environment','balance','is_native','value_usd','balance_observed_at','price','pools','pools_recorded','pools_omitted')
+    asset_fields=('id','chain_id','address','symbol','name','environment','balance','is_native','value_usd','balance_observed_at','price','pools','pools_recorded','pools_omitted','exit_quote_recorded')
     return [{**row,'assets':[{key:asset[key] for key in asset_fields if key in asset and
                            (asset[key] is not None or key in ('value_usd','price'))}
                           for asset in row['assets']]} for row in rows]
 
+def recorded_valuation(assets):
+    """Explicit disjoint categories over the full recorded inventory, before paging."""
+    from decimal import Decimal, InvalidOperation, localcontext
+    groups={'native':[], 'mintclub':[], 'other_tokens':[]}
+    unpriced=0
+    for asset in assets:
+        if asset.get('environment')!='mainnet':continue
+        try:value=Decimal(str(asset.get('value_usd')))
+        except InvalidOperation:unpriced+=1;continue
+        if not value.is_finite() or value<0:unpriced+=1;continue
+        category='native' if asset.get('is_native') else 'mintclub' if asset.get('curve_state') or asset.get('exit_route')=='mintclub_burn' else 'other_tokens'
+        groups[category].append((value,(asset.get('price') or {}).get('observed_at')))
+    def summarize(rows):
+        times=[time for _,time in rows if time]
+        with localcontext() as context:
+            context.prec=100
+            value=format(sum((value for value,_ in rows),Decimal(0)),'f') if rows else None
+        return {'estimated_value_usd':value,'priced_position_count':len(rows),
+                'price_observed_at':{'from':min(times,default=None),'to':max(times,default=None)},
+                'price_time_unknown_count':sum(time is None for _,time in rows)}
+    return {'scope':'Full recorded mainnet inventory, before pagination. Categories are disjoint.',
+            'all_priced_positions':summarize([row for rows in groups.values() for row in rows]),
+            'categories':{name:summarize(rows) for name,rows in groups.items()},'unpriced_mainnet_count':unpriced,
+            'interpretation':'Estimated recorded priced subset at separate observation times. Not a floor on current wealth or realizable proceeds. Missing values remain unknown; indicative prices are not executable quotes.'}
+
 def wallet_facts(wallets, *, pool_budget=40_000):
     def pick(value, names): return {k:value.get(k) for k in names}
     rows = []
     for wallet in wallets:
         row = pick(wallet,('address','tags','name','snapshot_id','analysed_at','prices_at','balance_observed_at','known_value_usd','unpriced_count','status'))
         if not wallet.get('analysed_at'): row['known_value_usd']=None
+        row['recorded_valuation']=wallet.get('recorded_valuation') or recorded_valuation(wallet['assets'])
         row['chains'] = [pick(c,('id','name','environment','complete','rpc_available','rpc_status','market_pending','market_errors','native_symbol','native_balance','native_observed_at','native_block_number','registry_block_number','discovery_status','registry_complete','registry_phase','rpc_pending','candidate_balance_errors','candidate_deferred')) for c in wallet['chains']]
         row['snapshot_price_references'] = wallet.get('snapshot_price_references',{})
         row['assets'] = []
@@ -159,6 +191,7 @@ def wallet_facts(wallets, *, pool_budget=40_000):
             item = pick(asset,('id','chain_id','address','symbol','name','environment','balance','is_native','value_usd','balance_observed_at'))
             item['price'] = pick(asset['price'],('usd','basis','quality','observed_at')) if asset.get('price') else None
             item['exit_quote'] = asset.get('exit_quote')
+            item['exit_quote_recorded'] = asset.get('exit_quote') is not None
             item['exit_route'] = asset.get('exit_route')
             item['markets'] = asset.get('links',[])
             pools=asset.get('market_pools',[]);item['pools']=[];item['pools_recorded']=len(pools)

package/kira_jobs.py

@@ -364,17 +364,34 @@ class JobStore:
             if a is not None and b is not None and a.get('wallet_balance') is not None and b.get('wallet_balance') is not None:
                 try:
                     with localcontext() as context:
-                        context.prec=100;delta=str(Decimal(b['wallet_balance'])-Decimal(a['wallet_balance']))
+                        context.prec=100
+                        first,last=Decimal(a['wallet_balance']),Decimal(b['wallet_balance'])
+                        if first.is_finite() and last.is_finite():delta=str(last-first)
                 except InvalidOperation:pass
             changes.append({'chain_id':identity[0],'address':identity[1],'token_id':identity[2],
                 'symbol':(b or a).get('symbol'),'before_balance':a.get('wallet_balance') if a else None,
                 'after_balance':b.get('wallet_balance') if b else None,'balance_delta':delta,
+                'balance_comparison':'unknown' if delta is None else 'unchanged_observations' if Decimal(delta)==0 else 'different_observations',
+                'activity_cause':'unknown_without_transfer_history',
                 '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'))})
+        def counts(rows):
+            return {'position_count':len(rows),
+                'new_record_count':sum(r['presence']=='new_record' for r in rows),
+                'absent_record_count':sum(r['presence']=='absent_record' for r in rows),
+                'missing_before_balance_count':sum(r['before_balance'] is None for r in rows),
+                'missing_after_balance_count':sum(r['after_balance'] is None for r in rows),
+                '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',
+            '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'),
-            'positions':changes,'note':'Absent records are unknown, not zero. 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.'}
+            '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.'}
 
     def snapshots(self, wallet):
         key = self.wallet(wallet)['address_key']

package/kira_research_tools.py

@@ -60,11 +60,12 @@ class ResearchTools:
         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_agent import wallet_facts, compact_wallet_facts
+        from kira_agent 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'])
+        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,

package/onchain.cjs

@@ -9,21 +9,27 @@ const runtime=JSON.parse(resolved.stdout);
 const root=runtime.data_root;
 const networks=JSON.parse(fs.readFileSync(path.join(assets,'sources/rpc-candidates.json')));
 const bondAbi=JSON.parse(fs.readFileSync(path.join(assets,'sources/mintclub-bond-abi.json')));
-const {RpcPool}=require('./rpc-pool.cjs');
+const {RpcPool,RouteRecorder}=require('./rpc-pool.cjs');
 const pool=new RpcPool({publicUrls:networks.flatMap(n=>n.public_rpc||[]),healthFile:runtime.health_file});
 function endpoints(chainId){return runtime.endpoints[String(chainId)] || [];}
 const endpointReads=new WeakMap();
+const endpointOutcomes=new WeakMap();
 const clientState=new WeakMap();
-function resilientTransport(chainId,urls,transport=viem.http,onSuccess=()=>{}) {
-  return pool.transport(chainId,urls,transport,onSuccess);
+function resilientTransport(chainId,urls,transport=viem.http,onSuccess=()=>{},onOutcome=()=>{}) {
+  return pool.transport(chainId,urls,transport,onSuccess,onOutcome);
 }
 function client(chainId,url) {
   const urls=endpoints(chainId);
   const index=url==null?0:urls.indexOf(url);
   const ordered=url==null?urls:index<0?[url]:urls.slice(index);
   const used=new Set();
+  const outcomes=new RouteRecorder();
   const state={chainId,last:null};
-  const c=viem.createPublicClient({transport:resilientTransport(chainId,ordered,viem.http,(i,endpoint)=>{used.add(urls.indexOf(ordered[i]));state.last=endpoint;})});
+  const c=viem.createPublicClient({transport:resilientTransport(chainId,ordered,viem.http,(i,endpoint)=>{used.add(urls.indexOf(ordered[i]));state.last=endpoint;},(i,event)=>{
+    const endpoint=urls.indexOf(ordered[i]),endpointClass=pool.publicUrls.has(ordered[i])?'public':'custom';
+    outcomes.record(endpoint,endpointClass,event);
+  })});
+  endpointOutcomes.set(c,outcomes);
   clientState.set(c,state);
   endpointReads.set(c,used);return c;
 }
@@ -52,4 +58,5 @@ function safeError(error){
   return diagnostic;
 }
 function rpcEndpointsUsed(c){return [...(endpointReads.get(c)||[])].filter(i=>i>=0).sort((a,b)=>a-b);}
-module.exports={viem,root,assets,networks,bondAbi,endpoints,client,connect,snapshotBlock,resilientTransport,rpcEndpointsUsed,serialize,safeError};
+function rpcRoutes(c){return endpointOutcomes.get(c)?.snapshot()||[];}
+module.exports={viem,root,assets,networks,bondAbi,endpoints,client,connect,snapshotBlock,resilientTransport,rpcEndpointsUsed,rpcRoutes,serialize,safeError};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kira-wallet",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Manage your wallets with your own AI. Track tokens, research markets and refresh holdings in a local workspace.",
   "license": "MIT",
   "private": false,

package/pipeline-onchain.cjs

@@ -41,9 +41,10 @@ async function parallel(items, workers, fn) {
   }));
   return results;
 }
-async function connect(n) {
+async function connect(n, onClient=()=>{}) {
   if(!h.endpoints(n.chain_id).length)throw new Error('No RPC endpoint configured; public fallback is disabled.');
   const c=h.client(n.chain_id);
+  onClient(c);
   if(await c.getChainId()!==n.chain_id)throw new Error('RPC chain identity mismatch');
   endpointIdentity.set(c,h.rpcEndpointsUsed(c)[0]??0);return c;
 }
@@ -149,7 +150,7 @@ async function scanChain(input, n, output, baseline=false) {
     let checkpoint=fs.existsSync(checkpointFile)?JSON.parse(fs.readFileSync(checkpointFile)):null;
     if(checkpoint&&(checkpoint.wallet!==input.wallet.toLowerCase()||checkpoint.chain_id!==n.chain_id||checkpoint.fingerprint!==fingerprint&&(!checkpoint.candidates||checkpoint.candidates.some(a=>!candidates.includes(a)))))
       throw new Error('Saved balance checkpoint does not match this research request. Start a new holdings analysis.');
-    const c = await connect(n), snapshot = await h.snapshotBlock(c,checkpoint),block=snapshot.number;rpcClient=c;
+    const c = await connect(n,c=>{rpcClient=c;}), snapshot = await h.snapshotBlock(c,checkpoint),block=snapshot.number;
     checkpoint=checkpoint||{wallet:input.wallet.toLowerCase(),chain_id:n.chain_id,block_number:block.toString(),block_hash:snapshot.hash,observed_at:stamp(),balances:{}};
     checkpoint.fingerprint=fingerprint;checkpoint.candidates=candidates;row.candidate_fingerprint=fingerprint;
     row.preferred_endpoint_index=endpointIdentity.get(c);
@@ -233,6 +234,7 @@ async function scanChain(input, n, output, baseline=false) {
     row.status = row.registry_scan.complete && errors.length===0?'complete':'partial';
   } catch(e) {row.error=h.safeError(e);}
   row.rpc_endpoint_indices=h.rpcEndpointsUsed(rpcClient);
+  row.rpc_routes=h.rpcRoutes(rpcClient);
   row.endpoint_index=row.rpc_endpoint_indices.length===1?row.rpc_endpoint_indices[0]:null;
   write(file,row);
   emitChain(row);

package/rpc-pool.cjs

@@ -64,6 +64,26 @@ function blockTag(request) {
   const tag = request.params?.[1];
   return ['eth_call','eth_getBalance','eth_getCode'].includes(request.method) && typeof tag === 'string' && /^0x[0-9a-f]+$/i.test(tag) ? tag.toLowerCase() : null;
 }
+class RouteRecorder {
+  constructor() { this.rows=new Map();this.overflow=new Map(); }
+  record(index, endpointClass, event) {
+    if(!['public','custom'].includes(endpointClass)||!['succeeded','failed','skipped','queue_timeout'].includes(event.outcome))return;
+    const row={endpoint_index:Number.isInteger(index)?index:null,endpoint_class:endpointClass,
+      method:/^[a-zA-Z0-9_]{1,64}$/.test(event.method||'')?event.method:'other',outcome:event.outcome};
+    if(['transport','throttle','size','method','contract','cooldown'].includes(event.reason))row.reason=event.reason;
+    for(const name of ['http_status','rpc_code'])if(Number.isSafeInteger(event[name]))row[name]=event[name];
+    const key=JSON.stringify(row);
+    let saved=this.rows.get(key);
+    if(!saved && this.rows.size<96){saved={...row,count:0};this.rows.set(key,saved);}
+    if(!saved){
+      const bucket=endpointClass+':'+event.outcome;
+      saved=this.overflow.get(bucket);
+      if(!saved){saved={endpoint_class:endpointClass,outcome:event.outcome,aggregated_overflow:true,count:0};this.overflow.set(bucket,saved);}
+    }
+    saved.count=Math.min(Number.MAX_SAFE_INTEGER,saved.count+1);
+  }
+  snapshot(){return [...this.rows.values(),...this.overflow.values()].map(row=>({...row}));}
+}
 class RpcPool {
   constructor({publicUrls = [], healthFile = null, interval = 2000, deadline = 12000, attemptTimeout = 4000, cooldown = 60000} = {}) {
     this.publicUrls = new Set(publicUrls); this.healthFile = healthFile;
@@ -123,13 +143,13 @@ class RpcPool {
       finally { clearTimeout(timer); signal.removeEventListener('abort', abort); }
     } finally { release(); }
   }
-  async run(chain, choices, request, transport, options, onSuccess, signal, deadlineAt) {
+  async run(chain, choices, request, transport, options, onSuccess, signal, deadlineAt, onOutcome) {
     let last = failure('RPC providers are temporarily unavailable. Retry holdings shortly.');
     let attempts = 0;
     for (const [index, url] of choices.entries()) {
       if (signal.aborted) throw signal.reason;
       const state = this.state(chain, url, transport, options);
-      if (state.until > Date.now() || (state.methods.get(request.method) || 0) > Date.now()) {last=state.error||last;continue;}
+      if (state.until > Date.now() || (state.methods.get(request.method) || 0) > Date.now()) {onOutcome(index,{method:request.method,outcome:'skipped',reason:'cooldown'});last=state.error||last;continue;}
       // An endpoint attempt includes its queue, cold verification and family pacing.
       // Public outages must leave time for the personal backup's actual read.
       const remaining=deadlineAt-Date.now();
@@ -140,11 +160,13 @@ class RpcPool {
       signal.addEventListener('abort',abort,{once:true});
       const timer=budget<remaining?setTimeout(()=>controller.abort(failure('RPC endpoint attempt timed out.', 'TimeoutError')),budget):null;
       let release;
+      let attempted=false;
       try {
         release=await state.gate.acquire(controller.signal);
         // A request ahead of us may have cooled this endpoint while we waited.
-        if (state.until > Date.now() || (state.methods.get(request.method) || 0) > Date.now()) {last=state.error||last;continue;}
+        if (state.until > Date.now() || (state.methods.get(request.method) || 0) > Date.now()) {onOutcome(index,{method:request.method,outcome:'skipped',reason:'cooldown'});last=state.error||last;continue;}
         if (++attempts > 4) break;
+        attempted=true;
         const timeout=attempts===1?this.attemptTimeout:Math.min(this.attemptTimeout,2000);
         if (!state.verified) {
           const id = await this.send(state, {method:'eth_chainId'}, controller.signal, timeout);
@@ -168,11 +190,18 @@ class RpcPool {
           throw error;
         }
         onSuccess(index, state); state.strikes = 0;state.error=null;
+        onOutcome(index,{method:request.method,outcome:'succeeded'});
         if (state.until) { state.until = 0; this.persist(); }
         return result;
       } catch (error) {
-        if (signal.aborted) throw signal.reason;
         last = error;state.error=error; const kind = classify(error);
+        const event={method:request.method,outcome:attempted?'failed':'queue_timeout',reason:kind};
+        for(let cause=error,depth=0;cause&&depth<10;cause=cause.cause,depth++){
+          if(Number.isInteger(cause.status))event.http_status=cause.status;
+          if(Number.isInteger(cause.code))event.rpc_code=cause.code;
+        }
+        onOutcome(index,event);
+        if (signal.aborted) throw signal.reason;
         if (kind === 'contract' || kind === 'size') throw error;
         if (kind === 'method') state.methods.set(request.method, Date.now() + 300000);
         else {
@@ -184,7 +213,7 @@ class RpcPool {
     }
     throw last;
   }
-  transport(chain, urls, transport = viem.http, onSuccess = () => {}) {
+  transport(chain, urls, transport = viem.http, onSuccess = () => {}, onOutcome = () => {}) {
     if (!urls.length) throw failure('No configured RPC endpoint for this chain.');
     const pool = this;
     // Leave time for a personal backup after two public providers. Preserve explicit custom-first order.
@@ -203,7 +232,8 @@ class RpcPool {
         if (external?.aborted) abort(); else external?.addEventListener('abort', abort, {once:true});
         const deadlineAt=Date.now()+pool.deadline;
         const timer = setTimeout(() => controller.abort(failure('RPC read deadline exceeded. Retry holdings.', 'TimeoutError')), pool.deadline);
-        const promise = pool.run(chain, choices.map(row=>row.url), request, transport, options, (index,state)=>onSuccess(choices[index].index,state), controller.signal,deadlineAt).then(value => {
+        const promise = pool.run(chain, choices.map(row=>row.url), request, transport, options, (index,state)=>onSuccess(choices[index].index,state), controller.signal,deadlineAt,
+          (index,event)=>onOutcome(choices[index].index,event)).then(value => {
           if (hash) { if (pool.cache.size >= 512) pool.cache.delete(pool.cache.keys().next().value); pool.cache.set(key, {value,expires:Date.now()+300000}); }
           return value;
         }).finally(() => { clearTimeout(timer); external?.removeEventListener('abort', abort); if (pool.pending.get(key) === promise) pool.pending.delete(key); });
@@ -213,4 +243,4 @@ class RpcPool {
     });
   }
 }
-module.exports = {RpcPool, classify};
+module.exports = {RpcPool, RouteRecorder, classify};

package/sources/rpc-candidates.json

@@ -27,8 +27,7 @@
     "chain_id_source": "https://github.com/wevm/viem/blob/main/src/chains/definitions/base.ts",
     "public_rpc": [
       "https://base-rpc.publicnode.com",
-      "https://base.drpc.org",
-      "https://public.1rpc.io/base"
+      "https://base.drpc.org"
     ],
     "explorer": "https://basescan.org",
     "public_rpc_sources": [
@@ -143,9 +142,12 @@
     "mintclub_bond_address": "0xc5a076cad94176c2996B32d8466Be1cE757FAa27",
     "chain_id_source": "https://github.com/wevm/viem/blob/main/src/chains/definitions/shibarium.ts",
     "public_rpc": [
-      "https://rpc.shibrpc.com"
+      "https://rpc.shibarium.shib.io"
     ],
-    "explorer": "https://shibariumscan.io"
+    "explorer": "https://shibariumscan.io",
+    "public_rpc_sources": [
+      "https://docs.shib.io/get-started/deploy-contracts"
+    ]
   },
   {
     "network": "cyber",
@@ -155,9 +157,13 @@
     "mintclub_bond_address": "0xc5a076cad94176c2996B32d8466Be1cE757FAa27",
     "chain_id_source": "https://github.com/wevm/viem/blob/main/src/chains/definitions/cyber.ts",
     "public_rpc": [
+      "https://rpc.cyber.co",
       "https://cyber.alt.technology"
     ],
-    "explorer": "https://cyberscan.co"
+    "explorer": "https://cyberscan.co",
+    "public_rpc_sources": [
+      "https://github.com/ethereum-optimism/superchain-registry/blob/main/chainList.toml"
+    ]
   },
   {
     "network": "ham",
@@ -299,9 +305,12 @@
     "mintclub_bond_address": "0x5dfA75b0185efBaEF286E80B847ce84ff8a62C2d",
     "chain_id_source": "https://github.com/wevm/viem/blob/main/src/chains/definitions/shibariumTestnet.ts",
     "public_rpc": [
-      "https://puppynet.shibrpc.com"
+      "https://rpc.puppynet.shib.io"
     ],
-    "explorer": "https://puppyscan.shib.io"
+    "explorer": "https://puppyscan.shib.io",
+    "public_rpc_sources": [
+      "https://docs.shib.io/get-started/deploy-contracts"
+    ]
   },
   {
     "network": "avalanchefuji",

package/viewer/details.py

@@ -35,6 +35,8 @@ def coverage_status(wallet, coverage):
     if not coverage: return 'Not researched'
     if coverage.get('rpc_pending') or coverage.get('rpc_status') == 'pending': return 'Research pending'
     if not coverage.get('rpc_available'): return 'RPC unavailable'
+    if coverage.get('registry_phase')=='deferred' or type(coverage.get('candidate_deferred')) is int and coverage['candidate_deferred']>0: return 'Research pending'
+    if any(type(coverage.get(k)) is int and coverage[k]>0 for k in ('candidate_balance_errors','balance_errors','registry_errors')) or coverage.get('registry_complete') is False: return 'Incomplete on-chain checks'
     if not coverage.get('complete'): return 'Incomplete discovery'
     return 'Researched'
 
@@ -87,7 +89,7 @@ def project_details(wallets, root):
             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'})
+                        'status': 'Held' if asset else 'No holding recorded' if coverage_status(wallet,coverage)=='Researched' else 'Unknown'})
             rows.append(row)
         token['wallets'] = rows
         held_rows = [r for r in rows if r['asset']]
@@ -107,7 +109,7 @@ def project_details(wallets, root):
             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
+            if not held and coverage_status(wallet,coverage)=='Researched' 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)})

package/viewer/static/app.js

@@ -267,10 +267,15 @@ function aggregateRow(a){
 }
 function renderNetworkTokens(network){
   const search=tokenSearch.trim().toLowerCase();
-  const assets=state.details.tokens.filter(a=>a.chain_id===network.id&&(minimum===0||(a.value_usd!=null&&a.value_usd>=minimum))&&(!search||[a.symbol,a.name,a.address||'native'].some(s=>s.toLowerCase().includes(search))));
+  const recorded=state.details.tokens.filter(a=>a.chain_id===network.id);
+  const assets=recorded.filter(a=>(minimum===0||(a.value_usd!=null&&a.value_usd>=minimum))&&(!search||[a.symbol,a.name,a.address||'native'].some(s=>s.toLowerCase().includes(search))));
   $('network-visible-count').textContent=assets.length;
   $('network-token-body').innerHTML=assets.map(aggregateRow).join('');
   $('network-token-table').hidden=assets.length===0;$('network-token-empty').hidden=assets.length>0;
+  if(!assets.length){
+    const empty=KiraView.networkEmpty(network,recorded.length);
+    $('network-token-empty').innerHTML=`<h3>${escapeHTML(empty.title)}</h3><p>${escapeHTML(empty.message)}</p>${empty.activity?'<a class="quiet-button" href="#/activity">View Activity</a>':''}`;
+  }
   bindImages();
 }
 function renderDetail(){

package/viewer/static/jobs.js

@@ -38,9 +38,13 @@ function refreshControlState(){
   $('service-mode').textContent=enabled?'Local controls':'Watch only';
   const sample=state?.demo===true;
   for(const id of ['open-wallet','empty-add-wallet','refresh-wallet','refresh-prices']){
-    const active=id.startsWith('refresh')&&jobList.some(j=>['queued','running'].includes(j.state)&&j.input.wallet===selectedWallet);
-    $(id).disabled=(sample&&id.startsWith('refresh'))||active||(id==='refresh-prices'&&!currentWallet()?.analysed_at);
-    $(id).title=sample?'Sample research cannot contact providers.':active?'A research job is already active for this wallet.':'';
+    const prices=id==='refresh-prices';
+    const active=id.startsWith('refresh')&&jobList.find(j=>KiraView.active(j)&&
+      (j.input.wallet||j.input.address)?.toLowerCase()===selectedWallet&&(!prices||j.operation==='prices.refresh'));
+    const missing=prices&&!currentWallet()?.analysed_at;
+    $(id).disabled=(sample&&id.startsWith('refresh'))||!!active||missing;
+    $(id).textContent=prices?(active?.state==='queued'?'Prices queued…':active?'Refreshing prices…':'Refresh prices'):$(id).textContent;
+    $(id).title=sample?'Sample research cannot contact providers.':active?(prices?'A price refresh is already '+active.state+' for this wallet.':'A research job is already active for this wallet.'):missing?'Wait for the first saved report before refreshing prices.':prices?'Update prices for the saved report. Detailed research pauses briefly and resumes automatically.':'';
   }
   $('discovery-refresh').disabled=$('refresh-wallet').disabled;
   if(typeof renderWatching==='function')renderWatching();

package/viewer/static/workspace-model.js

@@ -19,6 +19,13 @@
   const active = job => ['queued', 'running'].includes(job.state);
   const rpcGap = chain => (chain.rpc_available===false&&!chain.rpc_pending)||(chain.registry_complete===false&&!chain.rpc_pending&&chain.registry_phase!=='deferred')||chain.candidate_balance_errors>0;
   const coverageGap = chain => !chain.complete||rpcGap(chain)||chain.candidate_deferred>0||chain.market_pending||chain.market_errors>0;
+  function networkEmpty(network, recordedCount) {
+    if(recordedCount)return {title:'No tokens match these filters',message:'Lower the minimum value or clear your search to see recorded holdings.',activity:false};
+    const rows=network.wallets||[];
+    if(!rows.length||rows.some(r=>['Research pending','Awaiting analysis','Not researched'].includes(r.coverage)))return {title:'Research is pending on this network',message:'No holdings have been recorded here yet. Check Activity for progress or resume saved work. Missing records do not mean zero holdings.',activity:true};
+    if(rows.some(r=>r.coverage!=='Researched'))return {title:'No holdings recorded; coverage is incomplete',message:'Some checks could not establish holdings on this network. Review Activity and retry holdings when ready. Missing records remain unknown.',activity:true};
+    return {title:'No positive holdings recorded',message:'The completed checks found no positive holdings. Coverage can still omit tokens. Refresh holdings to check again.',activity:false};
+  }
   function discoveryNotice(wallet, readiness = null) {
     const chains=(wallet?.chains||[]).filter(c=>c.environment==='mainnet');
     const gaps=chains.filter(coverageGap);
@@ -62,7 +69,7 @@
     const h = Math.floor(seconds / 3600), m = Math.floor(seconds % 3600 / 60), s = seconds % 60;
     return (h ? h + 'h ' : '') + m + 'm ' + s + 's';
   }
-  const api = { catalog, pageSize, active, jobPresentation, duration, discoveryNotice, coverageGap };
+  const api = { catalog, pageSize, active, jobPresentation, duration, discoveryNotice, coverageGap, networkEmpty };
   if (typeof module !== 'undefined' && module.exports) module.exports = api;
   else root.KiraView = api;
 })(typeof globalThis !== 'undefined' ? globalThis : this);

package/wallet.py

@@ -256,6 +256,7 @@ def initial_result(wallet, folder, networks, discovered, chains, *, phase='basel
             'rpc_status':c.get('rpc_status','pending'),'native_symbol':NATIVE.get(n['chain_id'],'ETH'),
             'native_balance':c.get('native_balance'),'native_observed_at':c.get('observed_at'),
             'native_block_number':c.get('block_number'),'native_block_hash':c.get('block_hash'),
+            'rpc_endpoint_indices':c.get('rpc_endpoint_indices',[]),'rpc_routes':c.get('rpc_routes',[]),
             'general_erc20_discovery':'indexer_checked' if d.get('complete') else 'incomplete',
             'indexer_source':d.get('source'),'indexer_complete':d.get('complete',False),'indexer_pages':len(d.get('pages',[])),
             'discovery_status':d.get('discovery_status','pending'),'candidate_balance_errors':len(c.get('balance_errors',[])),
@@ -361,6 +362,7 @@ def finish(wallet, folder, networks, discovered):
              'native_observed_at':c['observed_at'],'native_block_number':c.get('block_number'),
              'native_block_hash':c.get('block_hash'),
              'rpc_endpoint_indices':c.get('rpc_endpoint_indices',[]),
+             'rpc_routes':c.get('rpc_routes',[]),
              'general_erc20_discovery':'indexer_checked' if d['complete'] else 'incomplete',
              'indexer_source':d['source'],'indexer_pages':len(d['pages']),'indexer_complete':d['complete'],
              'discovery_status':d.get('discovery_status','checked' if d['complete'] else 'incomplete'),