kira-wallet 0.1.10 → 0.1.12

package/README.md

@@ -48,6 +48,10 @@ include the same package and its checksum.
    stays visible. An AI or browser wallet connection does not enable an indexer.
 2. **Add a watching wallet.** Paste a public address and give it a name. Add more
    wallets whenever you need them. The form starts free research of native, common tokens and Mint Club assets, with keyless ERC20 transfer discovery on Ethereum, Base, Optimism, Arbitrum, Polygon and BNB. RPC checks candidate balances; unfinished history remains visible. First balances appear before detailed research finishes.
+   The basic scan saves usable results first. Choose **Start deep scan** for
+   additional discovery and one representative sell estimate per asset. Deep
+   scans show saved asset checks, available prices and unresolved checks. Pause
+   and resume from saved work at any time. Unknown coverage stays visible.
 3. **Connect your AI.** Install and sign in to the
    [Codex CLI](https://developers.openai.com/codex/cli) or
    [Claude Code](https://code.claude.com/docs/en/quickstart), then choose your

package/cashout-quotes.cjs

@@ -0,0 +1,87 @@
+'use strict';
+// Read-only, amount-specific pool quotes. These do not simulate token transfers.
+const {parseAbi,formatUnits}=require('viem');
+const v3Abi=parseAbi(['function quoteExactInputSingle((address tokenIn,address tokenOut,uint256 amountIn,uint24 fee,uint160 sqrtPriceLimitX96) params) returns (uint256 amountOut,uint160 sqrtPriceX96After,uint32 initializedTicksCrossed,uint256 gasEstimate)']);
+const aeroAbi=parseAbi(['function getAmountOut(uint256 amountIn,address tokenIn) view returns (uint256)']);
+const address=value=>typeof value==='string'&&/^0x[0-9a-fA-F]{40}$/.test(value);
+const integer=value=>{try{if(!/^[0-9]+$/.test(String(value)))return null;return BigInt(value);}catch{return null;}};
+
+function v2AmountOut(amount,reserveIn,reserveOut) {
+  if(amount<=0n||reserveIn<=0n||reserveOut<=0n)throw new Error('Pool quote input or reserves unavailable');
+  const withFee=amount*997n;
+  return withFee*reserveOut/(reserveIn*1000n+withFee);
+}
+function inputAmounts(balance) {
+  // A full-input quote can revert because of a pool's limits. Smaller inputs
+  // can establish a qualifying route, but failure of this finite search never
+  // proves that no other input or route can realize the threshold.
+  return [...new Set([balance,...[1n,2n,3n,4n,6n,8n].map(bits=>balance>>bits)].filter(n=>n>0n))];
+}
+function contractRevert(error) {
+  let reverted=false;
+  for(let cause=error,depth=0;cause&&depth<10;cause=cause.cause,depth++) {
+    if(['HttpRequestError','TimeoutError'].includes(cause.name)||cause.status||[-32005,-32603].includes(cause.code))return false;
+    if(['ContractFunctionRevertedError','ExecutionRevertedError'].includes(cause.name)||cause.code===3)reverted=true;
+  }
+  return reverted;
+}
+async function quotePool(client,network,token,pool,block,blockHash,deployments,{batchRead}={}) {
+  const state=pool.factory_measurement?.state||{},balance=integer(token.wallet_balance_raw);
+  const unknown=reason=>({status:'unknown',reason,gas_included:false,execution_verified:false});
+  if(!balance||!address(token.token_address)||!address(state.token0)||!address(state.token1)||state.token0.toLowerCase()===state.token1.toLowerCase()
+      ||pool.rpc_verification?.verification!=='official_factory_verified'||!pool.factory_measurement?.active_liquidity_verified
+      ||String(token.balance_block_number)!==String(block)||token.balance_block_hash!==blockHash)
+    return unknown('Verified pool and same-block holding evidence required');
+  const is0=state.token0.toLowerCase()===token.token_address.toLowerCase();
+  if(!is0&&state.token1.toLowerCase()!==token.token_address.toLowerCase())return unknown('Pool token identity mismatch');
+  const output=is0?state.token1:state.token0,measured=pool.factory_measurement;
+  if(!address(measured.quote_token)||measured.quote_token.toLowerCase()!==output.toLowerCase()||!Number.isInteger(measured.quote_decimals)||measured.quote_decimals<0||measured.quote_decimals>255)
+    return unknown('Output token metadata unavailable');
+  const canonical=protocol=>deployments.find(d=>d.chainId===network.chain_id&&d.protocol===protocol&&d.contract===(protocol==='v2'?'UniswapV2Factory':'UniswapV3Factory')&&d.address.toLowerCase()===state.factory?.toLowerCase());
+  const quoter=deployments.find(d=>d.chainId===network.chain_id&&d.protocol==='v3'&&d.contract==='QuoterV2'&&d.status==='active');
+  let kind,quote,request,decode;
+  if(canonical('v3')&&quoter&&Number.isInteger(state.fee)&&state.fee>=0&&state.fee<1_000_000) {
+    kind='uniswap_v3_quoter';
+    request=amount=>({address:quoter.address,abi:v3Abi,functionName:'quoteExactInputSingle',args:[{tokenIn:token.token_address,tokenOut:output,amountIn:amount,fee:state.fee,sqrtPriceLimitX96:0n}]});
+    decode=result=>result[0];
+  }else if(network.chain_id===8453&&state.factory?.toLowerCase()==='0x420dd381b31aef6683db6b902084cb0ffece40da'&&pool.venue==='aerodrome') {
+    kind='aerodrome_pool';
+    request=amount=>({address:pool.pool,abi:aeroAbi,functionName:'getAmountOut',args:[amount,token.token_address]});
+    decode=result=>result;
+  }else if(canonical('v2')&&Array.isArray(state.getReserves)) {
+    const reserveIn=integer(state.getReserves[is0?0:1]),reserveOut=integer(state.getReserves[is0?1:0]);
+    if(!reserveIn||!reserveOut)return unknown('Pool reserves unavailable');
+    kind='uniswap_v2_reserves';quote=async amount=>v2AmountOut(amount,reserveIn,reserveOut);
+  }else return unknown('Quote adapter unavailable for this verified pool');
+  if(request)quote=async amount=>decode(await client.readContract({...request(amount),blockNumber:block}));
+  const amounts=inputAmounts(balance);let failures=0,buffer=[];
+  for(let index=0;index<amounts.length;index++) {
+    const amount=amounts[index];
+    let result;
+    try{
+      // Keep the usual full-input fast path. Only fallback inputs are grouped,
+      // in their original order. QuoterV2 reverts its internal pool swap, so
+      // each exact-input call observes the same state in a read-only aggregate.
+      if(index>0&&request&&batchRead){
+        if(!buffer.length){
+          const group=amounts.slice(index,index+3);
+          buffer=await batchRead(group.map(request));
+          if(!Array.isArray(buffer)||buffer.length!==group.length)throw Error('Malformed quote batch');
+        }
+        const row=buffer.shift();
+        if(row.status!=='success')throw row.error||Error('Quote batch unavailable');
+        result=integer(decode(row.result));
+      }else result=integer(await quote(amount));
+    }
+    catch(error){if(error.code==='market_budget')throw error;failures++;if(contractRevert(error))continue;break;}
+    if(result===null){failures++;continue;}
+    if(result>0n)return {status:'quoted',kind,input_amount_raw:amount.toString(),input_amount_is_maximum:kind==='uniswap_v3_quoter',
+      holding_amount_raw:balance.toString(),output_amount_raw:result.toString(),output_amount:formatUnits(result,measured.quote_decimals),
+      input_address:token.token_address.toLowerCase(),pool:pool.pool,output_address:output.toLowerCase(),output_symbol:measured.quote_symbol,
+      output_decimals:measured.quote_decimals,block_number:String(block),block_hash:blockHash,
+      observed_at:new Date().toISOString(),route_fees_included:true,price_impact_included:true,gas_included:false,
+      execution_verified:false,transfer_tax_included:false,partial_input:amount<balance,source_url:pool.source_url};
+  }
+  return unknown(failures?'Pool quote failed; smaller-input and other routes remain unknown':'Sampled inputs returned zero; other routes remain unknown');
+}
+module.exports={v2AmountOut,inputAmounts,quotePool};

package/cashout-routes.cjs

@@ -0,0 +1,123 @@
+'use strict';
+// Bounded, read-only liquidation paths. Every next input comes from the previous
+// quoted output. A finite search never establishes that all routes were found.
+const {formatUnits}=require('viem');
+const catalog=require('./sources/known-tokens.json').tokens;
+const terminalAssets=new Set(catalog.filter(t=>['USDC','USDC.e','USDT','USDT0','DAI','WETH','WBNB','WAVAX','WMATIC'].includes(t.symbol)).map(t=>t.chain_id+':'+t.address.toLowerCase()));
+const terminal=(chain,address)=>terminalAssets.has(chain+':'+address.toLowerCase());
+const address=value=>typeof value==='string'&&/^0x[0-9a-fA-F]{40}$/.test(value);
+const integer=value=>{try{if(!/^(0|[1-9][0-9]{0,77})$/.test(String(value)))return null;const n=BigInt(value);return n<2n**256n?n:null;}catch{return null;}};
+
+function validLeg(quote,input,amount,block,hash) {
+  const used=integer(quote?.input_amount_raw),out=integer(quote?.output_amount_raw),decimals=quote?.output_decimals;
+  return quote?.status==='quoted'&&address(quote.input_address)&&quote.input_address.toLowerCase()===input.toLowerCase()
+    &&used>0n&&used<=amount&&integer(quote.holding_amount_raw)===amount&&out>0n&&address(quote.output_address)&&Number.isInteger(decimals)&&decimals>=0&&decimals<=255
+    &&quote.output_amount===formatUnits(out,decimals)&&String(quote.block_number)===String(block)&&quote.block_hash===hash
+    &&quote.route_fees_included===true&&quote.price_impact_included===true&&quote.gas_included===false&&!!quote.observed_at
+    &&(quote.kind!=='mintclub_burn'||quote.funded===true&&integer(quote.reserve_balance_raw)>=out);
+}
+
+function seedQuotes(token) {
+  const quotes=(token.dex_pools||[]).map(p=>p.cashout_quote).filter(Boolean).map(q=>({...q,input_address:token.token_address}));
+  const mint=token.mintclub,full=mint?.wallet_full_burn;
+  if(full&&full.gas_included===false&&!mint.wallet_full_burn_error)quotes.push({status:'quoted',kind:'mintclub_burn',input_address:token.token_address,
+    input_amount_raw:String(token.wallet_balance_raw),holding_amount_raw:String(token.wallet_balance_raw),
+    output_address:mint.reserve_token,output_amount_raw:String(full.net_refund_raw),output_amount:full.net_refund,
+    output_decimals:mint.reserve_decimals,block_number:String(mint.block_number),block_hash:mint.block_hash,
+    observed_at:mint.observed_at,route_fees_included:true,price_impact_included:true,gas_included:false,
+    funded:mint.funded,reserve_balance_raw:String(mint.reserve_balance_raw),royalty_raw:String(full.royalty_raw),
+    execution_verified:false,transfer_tax_included:false,source_url:mint.source_url});
+  return quotes;
+}
+
+function representativeQuote(token, routes=token.liquidation_routes||[]) {
+  const holding=integer(token.wallet_balance_raw),block=String(token.balance_block_number),hash=token.balance_block_hash;
+  if(!holding)return null;
+  for(const route of routes){
+    let input=token.token_address,amount=holding;
+    const visited=new Set([input.toLowerCase()]),pools=new Set();
+    const legs=route.legs;
+    if(!Array.isArray(legs)||!legs.length)continue;
+    if(legs.every(leg=>{
+      if(!validLeg(leg,input,amount,block,hash))return false;
+      const output=leg.output_address.toLowerCase(),pool=leg.pool?.toLowerCase();
+      if(visited.has(output)||pool&&pools.has(pool))return false;
+      visited.add(output);if(pool)pools.add(pool);input=output;amount=integer(leg.output_amount_raw);return true;
+    })&&terminal(token.chain_id,input)&&route.output_address?.toLowerCase()===input&&integer(route.output_amount_raw)===amount&&integer(route.holding_amount_raw)===holding)return route;
+  }
+  return seedQuotes(token).find(q=>validLeg(q,token.token_address,holding,block,hash)&&terminal(token.chain_id,q.output_address))||null;
+}
+
+async function expandRoutes(token,quoteAsset,{state,save=()=>{},maxLegs=4,maxNodes=32,maxBranches=4,maxSteps=Infinity,rootOnly=false,representative=false}={}) {
+  const holding=integer(token.wallet_balance_raw),block=String(token.balance_block_number),hash=token.balance_block_hash;
+  if(!holding||!address(token.token_address)||!/^0x[0-9a-fA-F]{64}$/.test(hash||''))throw new Error('Pinned route holding unavailable');
+  const identity=JSON.stringify([token.chain_id,token.token_address.toLowerCase(),token.token_type,holding.toString(),block,hash]);
+  if(state&&state.identity!==identity)throw new Error('Liquidation route checkpoint does not match the pinned holding');
+  if(state&&(!Array.isArray(state.pending)||!Array.isArray(state.routes)||!Array.isArray(state.unknown)||!Number.isSafeInteger(state.expanded)||state.expanded<0
+      ||state.root_quotes!==undefined&&!Array.isArray(state.root_quotes)
+      ||state.pending.some(node=>!address(node.address)||!integer(node.amount)||!Array.isArray(node.legs)||node.legs.length>=maxLegs||!Array.isArray(node.visited))))throw new Error('Invalid liquidation route frontier');
+  const finishRepresentative=()=>{
+    if(!representative||!representativeQuote(token,state.routes))return false;
+    state.pending=[];state.root_retry_pending=false;
+    state.unknown=[...new Set([...state.unknown,'One representative route is recorded. Alternative routes and the best achievable output remain unverified.'])];save(state);return true;
+  };
+  if(state&&finishRepresentative())return state;
+  // Pool verification can add root quotes after an early burn-only pass. A
+  // completed empty frontier must not hide those new amount-specific seeds.
+  const seeds=seedQuotes(token),signature=JSON.stringify(seeds.map(q=>[q.status,q.kind,q.pool?.toLowerCase(),q.input_amount_raw,q.holding_amount_raw,
+    q.output_address?.toLowerCase(),q.output_amount_raw,q.output_decimals,q.output_amount,q.block_number,q.block_hash,q.funded,q.reserve_balance_raw,
+    q.route_fees_included,q.price_impact_included,q.gas_included]).sort((a,b)=>JSON.stringify(a).localeCompare(JSON.stringify(b))));
+  if(state&&state.seed_signature!==signature)state=null;
+  state=state||{identity,pending:[{address:token.token_address.toLowerCase(),amount:holding.toString(),legs:[],visited:[token.token_address.toLowerCase()]}],routes:[],unknown:[],expanded:0};
+  state.seed_signature=signature;
+  save(state);
+  // A verified member can lack a root burn quote after a bulk detail/refund
+  // failure. Recover it through the normal paced, pinned read lane. Existing
+  // routes survive retries and successful root evidence survives restart.
+  const recoverRoot=token.mintclub_membership_status==='verified'&&!seeds.some(q=>q.kind==='mintclub_burn'&&validLeg(q,token.token_address,holding,block,hash));
+  if(recoverRoot&&!state.root_recovery_done){
+    state.root_retry_pending=true;save(state);
+    const recovered=await quoteAsset(token.token_address,holding,{mintOnly:true,knownMember:true});
+    state.root_quotes=recovered.filter(q=>validLeg(q,token.token_address,holding,block,hash));
+    state.root_retry_pending=recovered.some(q=>q.retryable===true);
+    state.root_recovery_done=!state.root_retry_pending;
+    state.root_error_kind=recovered.find(q=>q.retryable)?.failure_kind||null;
+    if(state.root_quotes.length&&!state.pending.some(node=>node.legs.length===0))
+      state.pending.unshift({address:token.token_address.toLowerCase(),amount:holding.toString(),legs:[],visited:[token.token_address.toLowerCase()]});
+    state.unknown=[...new Set([...state.unknown,...recovered.filter(q=>q.status!=='quoted').map(q=>q.reason).filter(Boolean)])];save(state);
+  }
+  let steps=0;
+  while(state.pending.length&&steps<maxSteps){
+    const node=state.pending[0];
+    if(rootOnly&&node.legs.length)break;
+    if(state.expanded>=maxNodes){state.unknown.push('Bounded route node limit reached; other liquidation paths remain unknown.');state.pending=[];save(state);break;}
+    // Leave the current node on the frontier if a time budget interrupts its
+    // reads. Successful RPC evidence and earlier route prefixes are retained.
+    const quotes=node.legs.length?await quoteAsset(node.address,BigInt(node.amount)):[...seeds,...(state.root_quotes||[])];
+    const valid=quotes.filter(q=>validLeg(q,node.address,BigInt(node.amount),block,hash));
+    if(valid.length!==quotes.length)state.unknown.push('Some route quotes failed or did not match the pinned amount and fee contract.');
+    if(!valid.length)state.unknown.push('No qualified amount-specific route at a recorded asset; absence is unproven.');
+    if(!valid.length&&(node.legs.length===0&&state.root_retry_pending||quotes.some(q=>q.retryable===true))){save(state);break;}
+    valid.sort((a,b)=>Number(terminal(token.chain_id,b.output_address))-Number(terminal(token.chain_id,a.output_address)));
+    if(valid.length>maxBranches)state.unknown.push('Bounded route branch limit reached; other routes remain unknown.');
+    for(const quote of valid.slice(0,representative?1:maxBranches)){
+      const output=quote.output_address.toLowerCase(),legs=[...node.legs,quote];
+      const repeatedPool=quote.pool&&node.legs.some(leg=>leg.pool?.toLowerCase()===quote.pool.toLowerCase());
+      if(node.visited.includes(output)||repeatedPool){state.unknown.push('Cyclic or reused-pool path not composed from unchanged pool states.');continue;}
+      if(terminal(token.chain_id,output)){
+        const route={status:'quoted',kind:'liquidation_path',input_amount_raw:legs[0].input_amount_raw,
+        holding_amount_raw:holding.toString(),output_address:output,output_amount_raw:quote.output_amount_raw,output_amount:quote.output_amount,
+        output_decimals:quote.output_decimals,block_number:block,block_hash:hash,observed_at:quote.observed_at,
+        route_fees_included:true,price_impact_included:true,gas_included:false,execution_verified:false,transfer_tax_included:false,legs};
+        const key=r=>JSON.stringify(r.legs.map(q=>[q.kind,q.pool?.toLowerCase(),q.input_address.toLowerCase(),q.input_amount_raw,q.output_address.toLowerCase(),q.output_amount_raw]));
+        if(!state.routes.some(r=>key(r)===key(route)))state.routes.push(route);
+      }
+      else if(legs.length>=maxLegs)state.unknown.push('Bounded liquidation leg limit reached; terminal cash proceeds remain unknown.');
+      else state.pending.push({address:output,amount:quote.output_amount_raw,legs,visited:[...node.visited,output]});
+    }
+    state.pending.shift();state.expanded++;steps++;state.unknown=[...new Set(state.unknown)];save(state);
+    if(finishRepresentative())break;
+  }
+  return state;
+}
+module.exports={terminal,validLeg,seedQuotes,representativeQuote,expandRoutes};

package/cashout.py

@@ -0,0 +1,159 @@
+"""USD 1 route eligibility. Never substitute spot holding value for proceeds."""
+from decimal import Decimal, InvalidOperation, localcontext
+import json
+from pathlib import Path
+import re
+
+CRITERIA = {'version': 2, 'minimum_quoted_usd': '1', 'mintclub_redemption_included': True,
+            'gas_included': False, 'execution_verified': False,
+            'scope': 'Recorded amount-specific routes only; unindexed and unsupported routes remain unknown.'}
+ADDRESS = re.compile(r'0x[0-9a-fA-F]{40}')
+HASH = re.compile(r'0x[0-9a-fA-F]{64}')
+_known = json.loads((Path(__file__).resolve().parent/'sources/known-tokens.json').read_text())['tokens']
+# Identity comes from the reviewed contract catalogue, never a provider's symbol.
+# Other reserve/output tokens need a further amount-specific liquidation leg.
+TERMINAL_ASSETS = {(row['chain_id'], row['address'].lower()) for row in _known
+                   if row['symbol'] in ('USDC', 'USDC.e', 'USDT', 'USDT0', 'DAI', 'WETH', 'WBNB', 'WAVAX', 'WMATIC')}
+
+
+def decimal(value):
+    text = str(value)
+    if len(text) > 350 or not re.fullmatch(r'[0-9]+(?:\.[0-9]+)?', text):
+        return None
+    try:
+        number = Decimal(text)
+        return number if number.is_finite() else None
+    except InvalidOperation:
+        return None
+
+
+def output_price(chain_id, address, market):
+    """Resolve the output asset's USD reference, never a nested curve spot."""
+    if not isinstance(address, str) or not ADDRESS.fullmatch(address):
+        return None
+    if (chain_id, address.lower()) not in TERMINAL_ASSETS:
+        return None
+    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:
+        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')
+                and row.get('observed_at') and row.get('source') and not row.get('retained_from_previous')):
+            return {**row, 'usd': format(price, 'f')}
+    return None
+
+
+def valid_path(token, quote, block, block_hash):
+    """Validate each liquidation amount, identity, pin and funded curve leg."""
+    legs=quote.get('legs')
+    if not isinstance(legs,list) or not 1<=len(legs)<=4:return False
+    address=token.get('token_address');available=decimal(token.get('wallet_balance_raw'))
+    seen={str(address).lower()};pools=set()
+    for index,leg in enumerate(legs):
+        if not isinstance(leg,dict):return False
+        used,out=decimal(leg.get('input_amount_raw')),decimal(leg.get('output_amount_raw'))
+        decimals=leg.get('output_decimals');output=leg.get('output_address')
+        if (not isinstance(address,str) or not ADDRESS.fullmatch(address) or
+                not isinstance(leg.get('input_address'),str) or leg['input_address'].lower()!=address.lower() or
+                used is None or not 0<used<=available or used!=used.to_integral_value() or decimal(leg.get('holding_amount_raw'))!=available or
+                out is None or not 0<out<2**256 or out!=out.to_integral_value() or
+                type(decimals) is not int or not 0<=decimals<=255 or not isinstance(output,str) or not ADDRESS.fullmatch(output) or
+                output.lower() in seen or str(leg.get('block_number'))!=block or leg.get('block_hash')!=block_hash or
+                leg.get('route_fees_included') is not True or leg.get('price_impact_included') is not True or
+                leg.get('gas_included') is not False or not leg.get('observed_at') or
+                leg.get('kind') not in ('mintclub_burn','uniswap_v2_reserves','uniswap_v3_quoter','aerodrome_pool')):return False
+        with localcontext() as context:
+            context.prec=800
+            if decimal(leg.get('output_amount'))!=out/(Decimal(10)**decimals):return False
+        if index==0 and used!=decimal(quote.get('input_amount_raw')):return False
+        if leg['kind']=='mintclub_burn':
+            backing=decimal(leg.get('reserve_balance_raw'))
+            if leg.get('funded') is not True or backing is None or out>backing:return False
+        elif not isinstance(leg.get('pool'),str) or not ADDRESS.fullmatch(leg['pool']) or leg['pool'].lower() in pools:return False
+        if leg.get('pool'):pools.add(leg['pool'].lower())
+        seen.add(output.lower());address=output;available=out
+    return (str(quote.get('output_address')).lower()==address.lower() and decimal(quote.get('output_amount_raw'))==available
+            and decimal(quote.get('output_amount'))==decimal(legs[-1].get('output_amount')))
+
+
+def classify(token, market, *, environment='mainnet'):
+    result = {'criteria_version': CRITERIA['version'], 'minimum_quoted_usd': '1',
+              'status': 'unknown', 'gas_included': False, 'execution_verified': False,
+              'excluded': False, 'quotes': [], 'unknown_routes': []}
+    if environment != 'mainnet':
+        result.update(status='outside_usd_scope', reason='Testnet assets have no USD eligibility classification.')
+        return result
+    holding = decimal(token.get('wallet_balance_raw'))
+    block, block_hash = str(token.get('balance_block_number')), token.get('balance_block_hash')
+    if (holding is None or holding <= 0 or holding != holding.to_integral_value()
+            or not re.fullmatch(r'[1-9][0-9]*', block)
+            or not isinstance(block_hash, str) or not HASH.fullmatch(block_hash)):
+        result['reason'] = 'Pinned holding identity unavailable.'
+        return result
+    routes = [p.get('cashout_quote') for p in token.get('dex_pools', [])]+token.get('liquidation_routes',[])
+    result['unknown_routes'].extend(token.get('liquidation_unknown_routes',[]))
+    mint = token.get('mintclub') or {}
+    full = mint.get('wallet_full_burn')
+    if full and not mint.get('wallet_full_burn_error'):
+        routes.append({'status': 'quoted', 'kind': 'mintclub_burn',
+                       'input_amount_raw': token['wallet_balance_raw'],
+                       'holding_amount_raw': token['wallet_balance_raw'],
+                       'output_amount': full.get('net_refund'), 'output_address': mint.get('reserve_token'),
+                       'block_number': mint.get('block_number'), 'block_hash': mint.get('block_hash'),
+                       'observed_at': mint.get('observed_at'), 'gas_included': full.get('gas_included'),
+                       'route_fees_included': True, 'price_impact_included': True,
+                       'reserve_balance': mint.get('reserve_balance'), 'funded': mint.get('funded')})
+    if mint.get('wallet_full_burn_error') or token.get('mintclub_error') or token.get('mintclub_pending'):
+        result['unknown_routes'].append('Mint Club redemption unavailable or pending.')
+    for quote in routes:
+        if not isinstance(quote, dict) or quote.get('status') != 'quoted':
+            result['unknown_routes'].append('Pool quote unavailable or unsupported.')
+            continue
+        amount, output = decimal(quote.get('input_amount_raw')), decimal(quote.get('output_amount'))
+        quoted_holding = decimal(quote.get('holding_amount_raw'))
+        if (amount is None or not 0 < amount <= holding or amount != amount.to_integral_value()
+                or quoted_holding != holding or output is None
+                or str(quote.get('block_number')) != block or quote.get('block_hash') != block_hash
+                or quote.get('gas_included') is not False or quote.get('route_fees_included') is not True
+                or quote.get('price_impact_included') is not True or not quote.get('observed_at')):
+            result['unknown_routes'].append('Quote does not match the pinned holding or fee contract.')
+            continue
+        if quote.get('kind') == 'mintclub_burn':
+            backing = decimal(quote.get('reserve_balance'))
+            if quote.get('funded') is not True or backing is None or output > backing:
+                result['unknown_routes'].append('Funded redemption backing not established.')
+                continue
+        if quote.get('kind')=='liquidation_path' and not valid_path(token,quote,block,block_hash):
+            result['unknown_routes'].append('Liquidation legs do not link to the pinned holding, funded backing and net outputs.')
+            continue
+        price = output_price(token['chain_id'], quote.get('output_address'), market)
+        if price is None:
+            result['unknown_routes'].append('Terminal output USD price unavailable; another liquidation leg or nested curve spot is not cash proceeds.')
+            continue
+        with localcontext() as context:
+            context.prec = 800
+            proceeds = output * Decimal(price['usd'])
+        result['quotes'].append({'kind': quote.get('kind'), 'input_amount_raw': str(quote['input_amount_raw']),
+                                 'output_amount': format(output, 'f'), 'output_address': quote['output_address'].lower(),
+                                 'quoted_output_usd': format(proceeds, 'f'), 'qualifies': proceeds >= Decimal('1'),
+                                 'block_number': block, 'block_hash': block_hash, 'observed_at': quote['observed_at'],
+                                 'output_price': price, 'partial_input': amount < holding,
+                                 'transfer_tax_included': quote.get('transfer_tax_included'),
+                                 **({'legs':quote['legs']} if quote.get('kind')=='liquidation_path' else {}),
+                                 'execution_verified': False, 'gas_included': False})
+    if any(q['qualifies'] for q in result['quotes']):
+        result['status'] = 'quoted_at_least_1_usd'
+    elif result['quotes']:
+        result['status'] = 'recorded_quotes_below_1_usd'
+    result['reason'] = 'Quotes are gas-excluded estimates. Transfer restrictions and other routes are not verified; no global exclusion is inferred.'
+    return result
+
+
+def annotate(snapshot, market):
+    environments = {c['chain_id']: c.get('environment') for c in snapshot.get('coverage', [])}
+    for token in snapshot.get('tokens', []):
+        token['cashout_eligibility'] = classify(token, market, environment=environments.get(token['chain_id'], 'unknown'))
+    snapshot['cashout_criteria'] = dict(CRITERIA)
+    snapshot['cashout_counts'] = {status: sum(t['cashout_eligibility']['status'] == status for t in snapshot.get('tokens', []))
+                                 for status in ('quoted_at_least_1_usd', 'recorded_quotes_below_1_usd', 'unknown', 'outside_usd_scope')}

package/discovery_state.py

@@ -0,0 +1,108 @@
+"""Durable discovery frontiers with immutable, bounded candidate segments."""
+import hashlib
+import json
+import os
+from pathlib import Path
+import re
+
+SEGMENT_SIZE = 512
+SEGMENT_FIELDS = ('contracts', 'tokens', 'completed_ranges', 'pending_ranges', 'blocked_ranges', 'seen_cursors')
+
+
+def encoded(value):
+    return (json.dumps(value, sort_keys=True, separators=(',', ':')) + '\n').encode()
+
+
+def atomic(path, value):
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_suffix(path.suffix + '.tmp')
+    with temporary.open('wb') as stream:
+        stream.write(encoded(value)); stream.flush(); os.fsync(stream.fileno())
+    os.replace(temporary, path)
+    descriptor = os.open(path.parent, os.O_RDONLY)
+    try:
+        os.fsync(descriptor)
+    finally:
+        os.close(descriptor)
+
+
+def identity(state, wallet, chain_id, provider):
+    if (not isinstance(state, dict) or state.get('wallet') != wallet.lower()
+            or type(state.get('chain_id')) is not int or state['chain_id'] != chain_id
+            or state.get('provider', provider) != provider):
+        raise ValueError('Discovery checkpoint identity mismatch.')
+
+
+def load(path, wallet, chain_id, provider):
+    path = Path(path)
+    if not path.exists():
+        return None
+    if path.stat().st_size > 4_000_000:
+        raise ValueError('Discovery manifest exceeds its supported size.')
+    manifest = json.loads(path.read_text())
+    if not isinstance(manifest, dict):
+        raise ValueError('Invalid discovery checkpoint.')
+    if 'storage_version' not in manifest:
+        # Version 0.1.10 used inline candidates. Migrate on the next saved page.
+        identity(manifest, wallet, chain_id, provider)
+        return manifest
+    if type(manifest.get('storage_version')) is not int or manifest['storage_version'] != 1 or not isinstance(manifest.get('sections'), dict):
+        raise ValueError('Unsupported discovery storage version.')
+    state = manifest.get('state')
+    identity(state, wallet, chain_id, provider)
+    state = dict(state)
+    for field, descriptors in manifest['sections'].items():
+        if field not in SEGMENT_FIELDS or not isinstance(descriptors, list):
+            raise ValueError('Invalid discovery segment manifest.')
+        values = []
+        for descriptor in descriptors:
+            if (not isinstance(descriptor, dict) or not isinstance(descriptor.get('sha256'), str)
+                    or not re.fullmatch(r'[0-9a-f]{64}', descriptor['sha256'])
+                    or type(descriptor.get('count')) is not int or not 1 <= descriptor['count'] <= SEGMENT_SIZE):
+                raise ValueError('Invalid discovery segment reference.')
+            chunk = path.parent / (path.stem + '.chunks') / (descriptor['sha256'] + '.json')
+            if chunk.stat().st_size > 1_000_000:
+                raise ValueError('Discovery segment exceeds its supported size.')
+            content = chunk.read_bytes()
+            if hashlib.sha256(content).hexdigest() != descriptor['sha256']:
+                raise ValueError('Discovery segment digest mismatch.')
+            part = json.loads(content)
+            if not isinstance(part, list) or len(part) != descriptor['count']:
+                raise ValueError('Invalid discovery segment contents.')
+            values.extend(part)
+        state[field] = values
+    return state
+
+
+def save(path, state, wallet, chain_id, provider):
+    path = Path(path)
+    identity(state, wallet, chain_id, provider)
+    header = {**state, 'provider': provider}
+    sections = {}
+    for field in SEGMENT_FIELDS:
+        if field not in header:
+            continue
+        values = header.pop(field)
+        if not isinstance(values, list):
+            raise ValueError('Discovery segment must be a list.')
+        sections[field] = []
+        for offset in range(0, len(values), SEGMENT_SIZE):
+            part = values[offset:offset + SEGMENT_SIZE]
+            content = encoded(part)
+            if len(content) > 1_000_000:
+                raise ValueError('Discovery segment exceeds its supported size.')
+            digest = hashlib.sha256(content).hexdigest()
+            chunk = path.parent / (path.stem + '.chunks') / (digest + '.json')
+            if chunk.exists():
+                if hashlib.sha256(chunk.read_bytes()).hexdigest() != digest:
+                    raise ValueError('Existing discovery segment digest mismatch.')
+            else:
+                atomic(chunk, part)
+            sections[field].append({'sha256': digest, 'count': len(part)})
+    manifest = {'storage_version': 1, 'state': header, 'sections': sections}
+    if len(encoded(manifest)) > 4_000_000:
+        raise ValueError('Discovery manifest exceeds its supported size.')
+    # Chunks are durable before the manifest advances. An interrupted write can
+    # leave an unused chunk, never a frontier referring to an unsaved page.
+    atomic(path, manifest)

package/docs/CLI.md

@@ -17,6 +17,18 @@ Registry publication remains an operator action. The code and original character
 
 ## Lifecycle
 
+Wallet registration and holdings refresh run a basic scan first. Use the saved
+result immediately, then choose **Start deep scan** in the wallet or Activity
+to check remaining networks and more complex markets. Deep scanning is optional,
+has no overall time limit, and supports **Pause scan** and **Resume deep scan**.
+It runs while Kira is running on this computer. App restart preserves saved
+results and requires an explicit resume for interrupted work.
+
+CLI equivalents are `kira jobs deepen BASIC_JOB_ID`, `kira jobs cancel JOB_ID`
+and `kira jobs resume JOB_ID`. A repeated deepen request uses the same child;
+it does not restart paused or finished work. Refreshing holdings starts a new
+basic scan. Neither basic nor deep completion guarantees all holdings or prices.
+
 Use `kira setup` for your first setup. For everyday use, `kira start` starts
 the local app with browser controls and opens it in your browser. The default
 port is 8787. Use `--port` to choose another port, or `--no-open` to print the