kira-wallet 0.1.5 → 0.1.6

package/README.md

@@ -140,3 +140,14 @@ From source, use `node bin/kira.cjs` in place of `kira`.
 Original code and Kira character assets are available under the [MIT license](LICENSE).
 Third-party artwork and references retain their own terms; see
 [Third-party notices](THIRD_PARTY_NOTICES.md).
+
+### Token coverage and optional Alchemy setup
+
+Kira uses free public RPC with bounded fallback and checks a selected common-token
+list alongside native assets and Mint Club. Other ERC20 holdings can be missing.
+Incomplete results show recovery guidance on Home and the wallet page. Connect
+your own Alchemy account for broader discovery on supported networks, then
+refresh holdings. Public RPC remains the first choice for ordinary reads;
+Alchemy is a backup and supplies the dedicated token inventory API. See the
+[step-by-step Alchemy guide](docs/ALCHEMY_SETUP.md) and
+[RPC behavior](docs/FREE_RPC.md).

package/docs/ALCHEMY_SETUP.md

@@ -0,0 +1,95 @@
+# Connect Alchemy to Kira
+
+Kira works with free public RPC by default. It checks native assets, selected
+common token contracts and the Mint Club registry. Other ERC20 holdings may
+be missing. For broader token discovery, connect your own Alchemy account.
+Kira runs these requests locally and does not operate a hosted relay.
+
+## Create an Alchemy app
+
+1. Sign in to the [Alchemy dashboard](https://dashboard.alchemy.com/).
+   A new account may already have a default app. Use it, or open your team
+   menu, Team Overview, Apps, then Create new app.
+2. Name the app and select the mainnets you want to research. Check that the
+   app has Node API and Portfolio API access for those networks. Create it.
+3. Copy the app API key. The Endpoints tab shows its network URLs. Kira's
+   combined Alchemy setup needs the key, so you do not need to copy each URL.
+
+These steps follow Alchemy's [official API key guide](https://www.alchemy.com/docs/create-an-api-key),
+checked on October 9, 2026. Dashboard wording can change.
+
+## Connect the key locally
+
+Create a private directory and file in your terminal:
+
+```sh
+mkdir -p ~/.config/kira
+touch ~/.config/kira/alchemy.env
+chmod 600 ~/.config/kira/alchemy.env
+```
+
+Open the file in a local text editor. On macOS, you can use:
+
+```sh
+open -e ~/.config/kira/alchemy.env
+```
+
+Add this line, replacing `YOUR_KEY` inside the editor:
+
+```dotenv
+ALCHEMY_API_KEY=YOUR_KEY
+```
+
+Save the file, then run:
+
+```sh
+kira config import-env --file ~/.config/kira/alchemy.env
+```
+
+For a non-default workspace, supply its existing `--data-dir` before `config`.
+Kira stores the file reference. Credentials stay outside the browser, chat and
+published analysis. Do not commit this file to a repository. A process
+environment variable with the same name overrides the file value; check that
+if an old key remains active.
+
+## Check the connection and refresh
+
+Open Workspace settings, then Manage data connection. Select Alchemy and use
+"I added my key · check again". Save the connection. Finding the local key
+does not prove the account, API or network is working.
+
+For an existing wallet, choose Refresh this wallet's holdings or Refresh
+holdings on its page. A new analysis confirms access and coverage. Old saved
+analyses retain their original observations and warnings. Saving a connection
+does not register a wallet or start research automatically.
+
+## What uses the key
+
+Ordinary balances prefer public RPC. After two failed or unavailable public
+providers, Kira tries the configured custom backup within the read deadline.
+Advanced settings can choose custom first or require custom only. Existing
+explicit custom-only restrictions remain in force.
+
+Alchemy token discovery uses the key directly. Standard public RPC cannot
+enumerate arbitrary ERC20 holdings. Kira uses Alchemy's
+[Tokens By Wallet endpoint](https://www.alchemy.com/docs/data/portfolio-apis/portfolio-api-endpoints/portfolio-api-endpoints/get-tokens-by-address),
+then verifies discovered candidates with on-chain balance reads.
+
+## If tokens are still missing
+
+- **Local key unavailable:** confirm the file exists, its variable name matches
+  the connection settings, and you ran the import command in the right workspace.
+- **Discovery failed:** check the app's enabled APIs and networks and Alchemy's
+  usage dashboard. Correct access or limits, then retry holdings.
+- **Some balances could not be checked:** wait briefly and retry. Public and
+  custom providers both have outages and limits. Review Advanced read preferences
+  if a custom-only endpoint is unavailable.
+- **Unsupported network:** broader discovery is unavailable there. Connecting
+  Alchemy cannot cover every network or every token. Known-contract reads remain
+  useful, and missing holdings remain unknown.
+
+Alchemy has account allowances and throughput limits. Check the current
+[plans](https://www.alchemy.com/docs/reference/pricing-plans) and API availability
+before selecting a plan. Kira does not create an account, subscribe or upgrade
+it. Public-first balance reads reduce ordinary use of the key; discovery still
+consumes Alchemy allowance. No connection guarantees a complete token inventory.

package/docs/CLI.md

@@ -10,7 +10,7 @@ npm install -g kira-wallet
 kira setup
 ```
 
-The operator published npm version 0.1.4. Version 0.1.5 is a preparation candidate. GitHub v0.1.3 remains
+The operator published npm version 0.1.5. Version 0.1.6 is a preparation candidate. GitHub v0.1.3 remains
 a draft; the previous archive and checksum are available from the
 [0.1.2 GitHub release](https://github.com/realproject7/kira-wallet/releases/tag/v0.1.2).
 Registry publication remains an operator action. The code and original character assets use the MIT license.
@@ -47,8 +47,8 @@ holdings. Missing coverage keeps the portfolio estimate partial. Existing snapsh
 an indexer; a price refresh does not discover missing tokens.
 
 Public RPC checks known assets and Mint Club. For broader ERC20 discovery,
-open Data provider connection, select Alchemy and follow its local key guide.
-The 0.1.5 candidate uses one save for Alchemy RPC and discovery; chain overrides
+open Custom RPC & token coverage, select Alchemy and follow its local key guide.
+Published 0.1.5 uses one save for Alchemy RPC and discovery; chain overrides
 remain under Advanced. Never paste the key into the browser. `kira doctor`
 checks whether the configured key is available. Configuration alone does not
 prove complete coverage; inspect the recorded results and gaps.
@@ -68,7 +68,7 @@ authentication. Verified adapter versions are Codex 0.158.x and Claude Code
 verified. This is a native CLI connection, with no Kira account, API-key proxy or
 hosted portfolio backend.
 
-In the 0.1.5 candidate, setup opens the existing Account / Permissions / Ready
+From published 0.1.5, setup opens the existing Account / Permissions / Ready
 modal directly. Choose Codex or Claude, then Use default model or a readable
 model choice. Codex choices come from bounded native metadata; Claude offers
 Sonnet, Opus and Haiku aliases. A catalog is not proof of account access.
@@ -212,3 +212,12 @@ in session storage. It clears password fields immediately. Recovery keeps the
 original encryption passphrase. No signing, key export or account deletion
 endpoint is exposed. OWS absence does not block ordinary address or browser
 wallet onboarding.
+
+## Free reads and broader token coverage
+
+Public RPC is preferred for ordinary reads, including when a custom backup is
+configured. Advanced settings can select custom first or custom only. For CLI
+configuration, use `kira rpc set --chain 8453 --url-env KIRA_BASE_RPC --priority
+public_first`. Existing custom-only choices remain unchanged. Alchemy token
+discovery uses the configured key directly. See [free RPC behavior](FREE_RPC.md)
+and the [Alchemy setup guide](ALCHEMY_SETUP.md).

package/docs/FREE_RPC.md

@@ -0,0 +1,85 @@
+# Free RPC reads and token coverage
+
+Kira contacts public providers directly from the local research process. No
+Kira relay or shared credential is required. Free public services are best
+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.
+
+## Request behavior
+
+- Chain identity is verified once per endpoint session and again after recovery.
+- One request runs per endpoint. Provider families share one queue and a
+  conservative two-second interval across chains. Two chain scans run at once.
+- A logical read has a twelve-second deadline including queues and verification.
+  The preferred HTTP attempt has four seconds, reserves at most two seconds.
+  Public attempts also have a total budget including verification and pacing,
+  leaving half the deadline for a configured personal backup.
+  Real fetches are aborted when a deadline expires. HTTP automatic retries are off.
+- At most four endpoint attempts run for a read. Public-first configurations
+  reserve an attempt for the personal backup after two public providers.
+- HTTP 429 and JSON-RPC backpressure cool an endpoint for at least sixty seconds.
+  Consecutive throttles increase this to at most thirty minutes. Retry-After
+  can extend the wait. Other transport failures have a short cooldown.
+- Unsupported methods have a method-specific penalty. Contract reverts do not
+  cool an otherwise healthy endpoint. Oversized Multicalls can split; outages and
+  throttling cannot create a burst of smaller calls.
+
+These are application limits, not promises about a provider's quota or uptime.
+Cooldown observations survive sequential research subprocesses in a bounded
+local cache. Custom endpoints and credentialed URLs are not written there.
+Status screens and onboarding checks do not probe RPC providers.
+
+## Snapshot consistency
+
+Each chain analysis records a block number and hash. Balance and contract reads
+keep that block. Before a fallback provider reads it, Kira verifies its header
+has the same hash. Every evidence read then uses an EIP-1898 block-hash selector
+with canonical checking. Providers that do not support it cannot supply that
+snapshot's evidence. Conflicting or unavailable evidence stays incomplete.
+No fallback silently substitutes `latest` for a fixed block.
+
+Identical concurrent reads share work. Successful fixed-block reads have a
+bounded cache keyed by chain, pinned hash, method and complete parameters,
+including the wallet address. Failed reads are evicted and never become zero.
+Wallet balances are not reused across wallets or new research processes.
+Registry identity caching remains separate from balances.
+
+## Default token inventory
+
+Native balances and the selected issuer/deployment-backed contracts in
+`sources/known-tokens.json` are checked before cold Mint Club enumeration.
+The small list includes USDC on seven supported mainnets, USDT on Ethereum and
+Avalanche, and WETH on Arbitrum. Decimals and quantities come from on-chain
+reads. This list does not cover all common tokens or all wrapped/bridged variants.
+
+The full Mint Club registry is still scanned. Public RPC cannot enumerate all
+arbitrary ERC20 contracts held by an address. Discovery remains incomplete
+without a working indexer on that network. Incomplete holdings show a persistent
+notice on Home and the wallet page, with a path to
+[Alchemy setup](ALCHEMY_SETUP.md) and an explicit holdings refresh.
+
+## Read preferences
+
+Public first is the default even when a custom connection is configured.
+Advanced settings provide custom first and custom only. Configurations without
+the new priority field use public first; an existing explicit custom-only choice
+continues to exclude public endpoints. RPC priority does not change the dedicated
+Alchemy discovery request.
+
+CLI example using an existing local endpoint variable:
+
+```sh
+kira rpc set --chain 8453 --url-env KIRA_BASE_RPC --priority public_first
+```
+
+Primary references: [EIP-1898](https://eips.ethereum.org/EIPS/eip-1898),
+[PublicNode](https://www.publicnode.com/),
+[dRPC limits](https://drpc.org/docs/howitworks/ratelimiting),
+[1RPC networks](https://docs.1rpc.io/overview/supported-networks),
+[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).

package/docs/RELEASE.md

@@ -44,19 +44,21 @@ RPC failures show affected networks, retry guidance and a settings action.
 Failed candidate balance reads keep the saved result and valuation partial
 even when general token discovery succeeded.
 
-The next candidate is **0.1.5**. It opens the existing setup modal directly,
-adds readable Codex and Claude model choices, and exposes model and permission
-changes in Workspace settings. New setup recommends local history; upgrades
-preserve explicit opt-outs. Watching wallet methods use individual buttons.
-Data provider connection offers one atomic Alchemy RPC and discovery save,
-with custom overrides under Advanced. A missing key keeps prior settings.
-The wallet draft survives a connection detour. Connecting still requires an
-explicit holdings refresh before missing assets can appear in saved evidence.
-
-Version 0.1.5 requires independent review and operator registry publication.
-It is not yet available from the registry. Keep published 0.1.4 and earlier
-package bytes immutable. The showcase remains a separate deployment.
-See [discovery acceptance](KIRA_DISCOVERY_ACCEPTANCE.md).
+Published **0.1.5** opens the existing setup modal directly, adds Codex and
+Claude model choices, exposes model and permission changes in Workspace settings,
+and provides one Alchemy connection save. Its registry version was confirmed on
+2026-10-09. Published package bytes remain immutable.
+
+The next candidate is **0.1.6**. It adds a paced local RPC pool, core-chain public
+alternatives, public-first custom backup, fixed-block hash checks and a small
+known-token catalog. Home and wallet pages display incomplete coverage with an
+Alchemy setup action. The settings guide explains account setup, private local
+key import and an explicit holdings refresh. Missing or malformed discovery data
+cannot become a completed empty inventory.
+
+Version 0.1.6 requires review and operator registry publication. It is not yet
+published. The showcase remains a separate deployment. See
+[free RPC behavior](FREE_RPC.md) and [Alchemy setup](ALCHEMY_SETUP.md).
 
 The operator published npm **0.1.2** on 2026-10-05. Its registry archive was
 downloaded and matched the reviewed GitHub archive above, including SHA-256,
@@ -78,7 +80,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 GitHub v0.1.1, its tag and its released archive immutable. Versions 0.1.2, 0.1.3 and 0.1.4 are also published and immutable. Do not rebuild them from later documentation
+Keep GitHub v0.1.1, its tag and its released archive immutable. Versions 0.1.2, 0.1.3, 0.1.4 and 0.1.5 are also published and immutable. Do not rebuild them from later documentation
 commits. Future package changes need a new version. Release preparation does not
 publish a GitHub release, merge PR 19, promote the website or publish to npm.
 Registry publication remains operator-only. The coding agent never publishes.
@@ -93,12 +95,12 @@ python3 scripts/prepare-release.py
 ```
 
 `prepare-release.py` scans the package boundary and creates
-`dist/kira-wallet-0.1.5.tgz`. The ignored `dist/release.json` records its source
+`dist/kira-wallet-0.1.6.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.5.tgz --access public
+npm publish ./dist/kira-wallet-0.1.6.tgz --access public
 ```
 
 Use the operator's npm account and complete authentication or OTP personally.

package/kira_cli.py

@@ -172,7 +172,7 @@ def main():
     imp=configsub.add_parser('import-env');imp.add_argument('--file',required=True);imp.add_argument('--key-env',default='ALCHEMY_API_KEY')
     rpc=sub.add_parser('rpc');rpcsub=rpc.add_subparsers(dest='setting',required=True)
     rpcsub.add_parser('public')
-    custom=rpcsub.add_parser('set');custom.add_argument('--chain',type=int,required=True);custom.add_argument('--url-env',required=True);fallback=custom.add_mutually_exclusive_group();fallback.add_argument('--public-fallback',action='store_true',default=None);fallback.add_argument('--custom-only',dest='public_fallback',action='store_false')
+    custom=rpcsub.add_parser('set');custom.add_argument('--chain',type=int,required=True);custom.add_argument('--url-env',required=True);custom.add_argument('--priority',choices=['public_first','custom_first']);fallback=custom.add_mutually_exclusive_group();fallback.add_argument('--public-fallback',action='store_true',default=None);fallback.add_argument('--custom-only',dest='public_fallback',action='store_false')
     discovery=sub.add_parser('discovery');discovery.add_argument('provider',choices=['none','alchemy']);discovery.add_argument('--key-env',default='ALCHEMY_API_KEY');discovery.add_argument('--explorers',action='store_true')
     args=parser.parse_args();root=Path(args.data_dir).expanduser().resolve();os.environ['KIRA_DATA_DIR']=str(root)
     if sys.version_info<(3,11):raise ValueError('Python 3.11 or newer is required.')
@@ -239,6 +239,7 @@ def main():
             elif args.setting=='public':cfg['rpc']['mode']='public'
             else:
                 cfg['rpc'].update(mode='custom')
+                if args.priority:cfg['rpc']['priority']=args.priority
                 if args.public_fallback is not None:cfg['rpc']['allow_public_fallback']=args.public_fallback
                 cfg['rpc']['chains'][str(args.chain)]={'url_env':args.url_env}
             # Validate before replacing the user's working configuration.

package/kira_config.py

@@ -16,7 +16,7 @@ def config_path():
     return Path(os.environ.get('KIRA_CONFIG', data_root()/'.kira.local.json')).expanduser()
 
 def default_config():
-    return {'schema_version':1,'rpc':{'mode':'public','allow_public_fallback':True,'chains':{}},
+    return {'schema_version':1,'rpc':{'mode':'public','allow_public_fallback':True,'priority':'public_first','chains':{}},
             'discovery':{'provider':'none','key_env':'ALCHEMY_API_KEY','explorers':False}}
 
 def provider_config(config, provider, key_env):
@@ -44,7 +44,8 @@ def load_config():
         raise ValueError('Invalid RPC configuration.')
     if not isinstance(discovery,dict) or discovery.get('provider') not in ('none','alchemy') or type(discovery.get('explorers',False)) is not bool:
         raise ValueError('Invalid discovery configuration.')
-    if set(rpc)-{'mode','allow_public_fallback','chains'} or set(discovery)-{'provider','key_env','explorers'}:raise ValueError('Unknown provider configuration fields.')
+    if rpc.get('priority','public_first') not in ('public_first','custom_first'):raise ValueError('Invalid RPC priority.')
+    if set(rpc)-{'mode','allow_public_fallback','priority','chains'} or set(discovery)-{'provider','key_env','explorers'}:raise ValueError('Unknown provider configuration fields.')
     if any(not isinstance(row,dict) or set(row)-{'url_env','alchemy_network'} for row in rpc['chains'].values()):raise ValueError('Unknown RPC endpoint fields.')
     for name in [discovery.get('key_env'),*[row.get('url_env') if isinstance(row,dict) else None for row in rpc['chains'].values()]]:
         if not isinstance(name,str) or not re.fullmatch(r'[A-Za-z_][A-Za-z0-9_]*',name):raise ValueError('Credentials must use valid environment references.')
@@ -97,7 +98,8 @@ def endpoints(network,cfg=None):
         # New setups default to automatic fallback. Preserve an explicit existing
         # opt-out for operators who require custom providers only.
         if not rpc['allow_public_fallback']:return urls
-    urls.extend(network.get('public_rpc') or [])
+    public=network.get('public_rpc') or []
+    urls=public+urls if rpc.get('priority','public_first')=='public_first' else urls+public
     return list(dict.fromkeys(urls))
 
 def runtime():
@@ -105,7 +107,7 @@ def runtime():
     try: values=secret_values(cfg)
     except ValueError: values={}
     return {'endpoints':{str(n['chain_id']):endpoints(n,cfg) for n in networks},
-            'secrets':list(values.values()),'data_root':str(data_root())}
+            'secrets':list(values.values()),'data_root':str(data_root()),'health_file':str(data_root()/'cache/rpc-health.json')}
 
 if __name__=='__main__':
     # Internal child-process channel only. The user CLI never emits this payload.

package/kira_jobs.py

@@ -128,6 +128,7 @@ class JobStore:
             raise JobError('invalid_envelope','Persisted job validation failed. Preserve the file for recovery.')
         names={'wallet.add':['address','tag'],'wallet.refresh':['wallet'],'prices.refresh':['wallet'],'wallet.setTags':['wallet','tags'],
             'settings.rpc':['mode','chains','allow_public_fallback'],'settings.discovery':['provider','key_env'],'settings.provider':['provider','key_env']}[job['operation']]
+        if job['operation']=='settings.rpc' and 'priority' in job['input']:names=names+['priority']
         fields(job['input'],names)
         wallet=job['input'].get('wallet') or job['input'].get('address')
         if wallet is not None and (not isinstance(wallet,str) or not ADDRESS.fullmatch(wallet)):raise JobError('invalid_envelope','Persisted wallet identity is invalid.')
@@ -160,7 +161,9 @@ class JobStore:
                 raise JobError('invalid_settings','Choose a data provider and a local credential reference.')
             return value.copy()
         if operation == 'settings.rpc':
-            fields(value,['mode','chains','allow_public_fallback'])
+            fields(value,['mode','chains','allow_public_fallback']+(['priority'] if isinstance(value,dict) and 'priority' in value else []))
+            if value.get('priority','public_first') not in ('public_first','custom_first'):
+                raise JobError('invalid_settings','Choose a valid RPC priority.')
             if value['mode'] not in ('public','custom') or type(value['allow_public_fallback']) is not bool or not isinstance(value['chains'],list) or len(value['chains'])>30:
                 raise JobError('invalid_settings','Choose a valid RPC mode and credential references.')
             available={n['chain_id'] for n in read(ASSETS/'sources/rpc-candidates.json')}
@@ -171,7 +174,7 @@ class JobStore:
                     raise JobError('invalid_settings','Use a known chain and a unique environment variable reference.')
                 chains[str(chain['chain_id'])]={'url_env':chain['url_env']}
             if value['mode']=='custom' and not chains:raise JobError('invalid_settings','Custom RPC requires at least one endpoint reference.')
-            return {'mode':value['mode'],'chains':chains,'allow_public_fallback':value['allow_public_fallback']}
+            return {'mode':value['mode'],'chains':chains,'allow_public_fallback':value['allow_public_fallback'],**({'priority':value['priority']} if 'priority' in value else {})}
         if operation == 'settings.discovery':
             fields(value,['provider','key_env'])
             if value['provider'] not in ('none','alchemy') or not isinstance(value['key_env'],str) or not re.fullmatch(r'[A-Z_][A-Z0-9_]{0,99}',value['key_env']):raise JobError('invalid_settings','Use a supported indexer and environment variable reference.')
@@ -404,6 +407,7 @@ class JobStore:
             config=load_config()
             if job['operation']=='settings.rpc':
                 updated={**job['input'],'chains':{key:dict(row) for key,row in job['input']['chains'].items()}}
+                updated.setdefault('priority',config['rpc'].get('priority','public_first'))
                 for key,row in updated['chains'].items():
                     previous=config['rpc']['chains'].get(key,{})
                     if row['url_env']==previous.get('url_env') and previous.get('alchemy_network'):row['alchemy_network']=previous['alchemy_network']

package/onchain.cjs

@@ -9,41 +9,32 @@ 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 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 clientState=new WeakMap();
 function resilientTransport(chainId,urls,transport=viem.http,onSuccess=()=>{}) {
-  if(!urls.length)throw new Error('No configured RPC endpoint for this chain.');
-  const choices=urls.map((url,index)=>options=>{
-    const inner=transport(url,{timeout:8000,retryCount:0})(options);
-    let verified=null;
-    return {...inner,request:async request=>{
-      if(!verified)verified=inner.request({method:'eth_chainId'}).then(id=>{
-        if(Number(BigInt(id))!==chainId)throw new Error('RPC chain identity mismatch');
-      }).catch(error=>{verified=null;throw error;});
-      await verified;
-      const result=await inner.request(request);
-      if(request.method==='eth_chainId'&&Number(BigInt(result))!==chainId){verified=null;throw new Error('RPC chain identity mismatch');}
-      onSuccess(index);
-      return result;
-    }};
-  });
-  return viem.fallback(choices,{rank:false,retryCount:0});
+  return pool.transport(chainId,urls,transport,onSuccess);
 }
 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 c=viem.createPublicClient({transport:resilientTransport(chainId,ordered,viem.http,i=>used.add(urls.indexOf(ordered[i])))});
+  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;})});
+  clientState.set(c,state);
   endpointReads.set(c,used);return c;
 }
 async function connect(chainId){
-  let error;
-  for(const url of endpoints(chainId)){
-    try{const c=client(chainId,url);if(await c.getChainId()!==chainId)throw new Error('RPC chain identity mismatch');return c;}
-    catch(e){error=e;}
-  }
-  throw error || new Error('No configured RPC endpoint for this chain.');
+  const c=client(chainId);await c.getChainId();return c;
+}
+async function snapshotBlock(c){
+  const header=await c.getBlock({blockTag:'latest'}),state=clientState.get(c);
+  if(!state||header.number==null)throw new Error('Snapshot block identity unavailable.');
+  pool.pin(state.chainId,header.number,header.hash,state.last);
+  return {number:header.number,hash:header.hash};
 }
 const serialize=data=>JSON.stringify(data,(_,v)=>typeof v==='bigint'?v.toString():v,2);
 function safeError(error){
@@ -60,4 +51,4 @@ 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,resilientTransport,rpcEndpointsUsed,serialize,safeError};
+module.exports={viem,root,assets,networks,bondAbi,endpoints,client,connect,snapshotBlock,resilientTransport,rpcEndpointsUsed,serialize,safeError};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kira-wallet",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Manage your wallets with your own AI. Track tokens, research markets and refresh holdings in a local workspace.",
   "license": "MIT",
   "private": false,
@@ -57,10 +57,14 @@
     "ows_bridge.cjs",
     "docs/KIRA_LIVE_QA.md",
     "docs/KIRA_DISCOVERY_ACCEPTANCE.md",
-    "kira_models.py"
+    "kira_models.py",
+    "rpc-pool.cjs",
+    "sources/known-tokens.json",
+    "docs/ALCHEMY_SETUP.md",
+    "docs/FREE_RPC.md"
   ],
   "scripts": {
-    "test": "python3 -m unittest discover -s . -p 'test_*.py' && python3 -m unittest discover -s viewer -p 'test_*.py' && node test-onchain.cjs && node --check viewer/static/app.js && node --check viewer/static/jobs.js && node test-workspace.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/agent.js && node test-agent-ui.cjs && node test-markdown.cjs && node --check viewer/static/report.js && node test-report-ui.cjs && node test-holdings-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/chat-workspace.js && node --check viewer/static/selects.js && node --check site/demo.js"
+    "test": "python3 -m unittest discover -s . -p 'test_*.py' && python3 -m unittest discover -s viewer -p 'test_*.py' && node test-onchain.cjs && node --check viewer/static/app.js && node --check viewer/static/jobs.js && node test-workspace.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/agent.js && node test-agent-ui.cjs && node test-markdown.cjs && node --check viewer/static/report.js && node test-report-ui.cjs && node test-holdings-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/chat-workspace.js && node --check viewer/static/selects.js && node --check site/demo.js && node test-rpc-pool.cjs"
   },
   "dependencies": {
     "viem": "2.57.2"

package/pipeline-onchain.cjs

@@ -40,13 +40,10 @@ async function parallel(items, workers, fn) {
   return results;
 }
 async function connect(n) {
-  const choices=h.endpoints(n.chain_id).map(url=>()=>h.client(n.chain_id,url));
-  let error;
-  for (const [index,create] of choices.entries()) {
-    try {const c = create(); if (await c.getChainId() !== n.chain_id) throw new Error('RPC chain identity mismatch'); endpointIdentity.set(c,index);return c;}
-    catch (e) {error = e;}
-  }
-  throw error || new Error('No RPC endpoint configured; public fallback is disabled.');
+  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);
+  if(await c.getChainId()!==n.chain_id)throw new Error('RPC chain identity mismatch');
+  endpointIdentity.set(c,h.rpcEndpointsUsed(c)[0]??0);return c;
 }
 function rpcFailure(error) {
   let sizeLimit=false,transportFailure=false;
@@ -69,7 +66,7 @@ async function calls(c, contracts, block) {
     return results;
   } catch (e) {
     const {sizeLimit,transportFailure}=rpcFailure(e);
-    if (!sizeLimit&&transportFailure) return contracts.map(()=>({status:'failure',error:e}));
+    if (!sizeLimit) return contracts.map(()=>({status:'failure',error:e}));
     if (contracts.length > 1) {
       const mid = Math.ceil(contracts.length/2);
       return [...await calls(c,contracts.slice(0,mid),block), ...await calls(c,contracts.slice(mid),block)];
@@ -78,10 +75,10 @@ async function calls(c, contracts, block) {
     catch (inner) {return [{status:'failure',error:inner}];}
   }
 }
-async function batches(c, contracts, block, size=100) {
+async function batches(c, contracts, block, size=32) {
   const plans = [];
   for (let i=0; i<contracts.length; i+=size) plans.push(contracts.slice(i,i+size));
-  return (await parallel(plans,3,b => calls(c,b,block))).flat();
+  return (await parallel(plans,1,b => calls(c,b,block))).flat();
 }
 async function registry(c, n, block) {
   const count = Number(await c.readContract({address:n.mintclub_bond_address,abi:h.bondAbi,functionName:'tokenCount',blockNumber:block}));
@@ -125,20 +122,29 @@ async function scanChain(input, n, output) {
   const row = {wallet:input.wallet,chain_id:n.chain_id,network:n.network,observed_at:stamp(),status:'unavailable',tokens:[],native_balance:null};
   let rpcClient;
   try {
-    const c = await connect(n), block = await c.getBlockNumber();rpcClient=c;
+    const c = await connect(n), snapshot = await h.snapshotBlock(c),block=snapshot.number;rpcClient=c;
     row.preferred_endpoint_index=endpointIdentity.get(c);
     row.block_number = block;
+    row.block_hash = snapshot.hash;
     row.native_balance = v.formatUnits(await c.getBalance({address:input.wallet,blockNumber:block}),18);
     row.rpc_status = 'available';
+    // Check discovered and built-in candidates before expensive cold registry work.
+    const initial=new Map(input.candidates.filter(t=>t.chain_id===n.chain_id).map(t=>[t.address.toLowerCase(),{...t,token_type:'ERC20'}]));
+    const initialTokens=[...initial.values()];
+    const initialBalances=await batches(c,initialTokens.map(t=>({address:t.address,abi:erc20,functionName:'balanceOf',args:[input.wallet]})),block);
+    const firstReads=new Map(initialTokens.map((t,i)=>[t.address.toLowerCase(),initialBalances[i]]));
     let reg;
     try {reg = await registry(c,n,block);} catch (e) {row.registry_error = h.safeError(e); reg = {count:null,entries:[],errors:1,cache_reused:0};}
     const plans = new Map();
-    for (const t of input.candidates.filter(t => t.chain_id===n.chain_id)) plans.set(t.address.toLowerCase(), {...t,token_type:'ERC20'});
+    for (const [key,t] of initial) plans.set(key,t);
     for (const t of reg.entries.filter(t => t.address && t.token_type && t.token_type!=='unknown')) {
       plans.set(t.address.toLowerCase(),{...plans.get(t.address.toLowerCase()),...t,registered_mintclub:true});
     }
     const tokens = [...plans.values()];
-    const balances = await batches(c,tokens.map(t => ({address:t.address,abi:t.token_type==='ERC1155'?erc1155:erc20,functionName:'balanceOf',args:t.token_type==='ERC1155'?[input.wallet,0n]:[input.wallet]})),block);
+    const remaining=tokens.filter(t=>!firstReads.has(t.address.toLowerCase())||t.token_type==='ERC1155');
+    const later=await batches(c,remaining.map(t => ({address:t.address,abi:t.token_type==='ERC1155'?erc1155:erc20,functionName:'balanceOf',args:t.token_type==='ERC1155'?[input.wallet,0n]:[input.wallet]})),block);
+    remaining.forEach((t,i)=>firstReads.set(t.address.toLowerCase(),later[i]));
+    const balances=tokens.map(t=>firstReads.get(t.address.toLowerCase()));
     const errors = []; let checked = 0, erc20Checked = 0, erc1155Checked = 0;
     const held = [];
     tokens.forEach((t,i) => {
@@ -192,7 +198,7 @@ function deployment(chain,protocol,name) {
   return deployments.find(r=>r.chainId===chain && r.protocol===protocol && r.contract.toLowerCase()===name.toLowerCase())?.address;
 }
 async function dexChain(n, tokens) {
-  const c=await connect(n),block=await c.getBlockNumber();
+  const c=await connect(n),block=(await h.snapshotBlock(c)).number;
   // Supplement DEX indexer discovery on Base with the canonical WETH/USDC factories.
   if (n.chain_id===8453) {
     const queries=[];
@@ -265,19 +271,19 @@ async function main() {
   const input=JSON.parse(fs.readFileSync(inputPath));
   if(!v.isAddress(input.wallet))throw new Error('Invalid wallet address');
   if(mode==='scan') {
-    const rows=await parallel(input.networks,4,n=>scanChain(input,n,outputPath));
+    const rows=await parallel(input.networks,2,n=>scanChain(input,n,outputPath));
     write(path.join(outputPath,'onchain-summary.json'),{wallet:input.wallet,observed_at:stamp(),chains:rows});
   }else if(mode==='dex') {
-    const result=await parallel(input.networks.filter(n=>input.tokens.some(t=>t.chain_id===n.chain_id)),4,async n=>{
+    const result=await parallel(input.networks.filter(n=>input.tokens.some(t=>t.chain_id===n.chain_id)),2,async n=>{
       const group=input.tokens.filter(t=>t.chain_id===n.chain_id);
       try{return await dexChain(n,group);}catch(e){group.forEach(t=>t.dex_verification_error=h.safeError(e));return group;}
     });
     write(outputPath,{wallet:input.wallet,observed_at:stamp(),tokens:result.flat()});
   }else if(mode==='reserves') {
-    const result=await parallel(input.networks.filter(n=>input.tokens.some(t=>t.chain_id===n.chain_id&&t.mintclub)),4,async n=>{
+    const result=await parallel(input.networks.filter(n=>input.tokens.some(t=>t.chain_id===n.chain_id&&t.mintclub)),2,async n=>{
       const rows=[];
       try {
-        const c=await connect(n),block=await c.getBlockNumber();
+        const c=await connect(n),block=(await h.snapshotBlock(c)).number;
         const queue=input.tokens.filter(t=>t.chain_id===n.chain_id&&t.mintclub).map(t=>t.token_address),seen=new Set();
         for(let i=0;i<queue.length;i++) {
           const address=queue[i],key=address.toLowerCase();