kira-wallet 0.1.4 → 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.3 on 2026-10-06. 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.
@@ -42,14 +42,14 @@ address or use the browser wallet picker. Registration starts one explicit
 research job; follow it in Activity and read the saved portfolio report.
 No signature, seed phrase or private key is needed.
 
-Candidate 0.1.4 explains limited discovery before wallet registration and beside
-holdings. Missing coverage keeps the portfolio estimate partial. It is not yet
-published to npm. Existing snapshots require a holdings refresh after connecting
+Published 0.1.4 explains limited discovery before wallet registration and beside
+holdings. Missing coverage keeps the portfolio estimate partial. Existing snapshots require a holdings refresh after connecting
 an indexer; a price refresh does not discover missing tokens.
 
 Public RPC checks known assets and Mint Club. For broader ERC20 discovery,
-open Research connections, select Alchemy and name the private environment
-variable holding its key. Never paste the key into the browser. `kira doctor`
+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,8 +68,12 @@ 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 setup, choose the CLI account and an optional model ID. The blank model field
-uses the CLI default. Choose no automatic wallet context, one registered wallet,
+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.
+Advanced accepts a custom identifier and preserves saved identifiers absent
+from the catalog. Workspace settings reopens the same selector and permissions. Choose no automatic wallet context, one registered wallet,
 or the whole recorded portfolio. A generic response check sends no wallet data
 and must pass before these settings are saved.
 
@@ -79,7 +83,10 @@ and contract identities, timestamps, unknown prices and coverage. Credentials,
 RPC endpoints, raw provider errors and local paths are excluded. Changing the
 provider, model, context or selected wallet creates a new conversation.
 
-Kira-local history is opt-in and uses private `conversations/` files. With history
+New setup in 0.1.5 recommends saving history and preselects it. Existing saved
+true and false choices are restored exactly. Saving lets you reopen chats after
+restart; it does not expand model memory or wallet access. The choice and
+research permission remain editable in Workspace settings. Kira-local history uses private `conversations/` files. With history
 off, conversations and drafts stay in memory. A new server process starts a fresh
 conversation; saved files remain available locally and are not automatically
 replayed. Native CLI, administrator policy and provider data policies remain a
@@ -135,8 +142,8 @@ kira config import-env --file /absolute/private/rpc.env --key-env ALCHEMY_API_KE
 ```
 
 The import references the file instead of copying keys. It configures Alchemy
-RPC and portfolio discovery separately, with public fallback enabled to match
-the historical engine. Environment overrides the file. Missing files or keys
+RPC and portfolio discovery together, preserving existing custom chain overrides
+and explicit fallback preferences. New configurations allow public fallback. Environment overrides the file. Missing files or keys
 produce limited coverage; malformed configuration fails with safe errors.
 The import does not contact providers. Private settings are never served.
 
@@ -205,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/JOB_CONTRACT.md

@@ -8,7 +8,8 @@ this contract. Chat interruption never cancels an engine job.
 Mutations use `{schema_version: 1, operation, input, idempotency_key}`.
 Supported operations are `wallet.add` (address, exact tag), `wallet.refresh`
 (wallet address or exact tag), `prices.refresh` (same), `wallet.setTags`
-(wallet, exact tags), `job.resume` and `job.cancel` (job_id).
+(wallet, exact tags), `settings.rpc`, `settings.discovery`, `settings.provider`,
+`job.resume` and `job.cancel` (job_id).
 Read operations are `job.read`, `job.list`, `snapshot.read`, and
 `snapshots.compare`. The portfolio projection retains its existing schema.
 
@@ -21,6 +22,17 @@ the same job without rerunning providers. Resume requeues the same job ID and
 increments its attempt on execution. Retain the key until the job is removed
 by a future explicit retention policy. Version mismatches fail closed.
 
+`settings.provider` accepts exactly `{provider: "public" | "alchemy", key_env}`.
+The key reference is a bounded environment variable name, never a credential.
+One writer-locked atomic replacement changes RPC mode and discovery together.
+Alchemy updates generated network references while preserving explicit custom
+chain overrides, unrelated chains, explorer choice and public fallback policy.
+A missing local key fails before replacement. Public mode keeps inactive custom
+references for later use. A detected key is not a validated provider or complete
+holdings result. Existing settings.rpc and settings.discovery requests remain
+compatible. The browser waits for terminal settings results; retrying a lost
+result checks the same accepted job instead of submitting another change.
+
 ## Envelope
 
 Each private `jobs/<uuid>.json` records schema_version, job_id, operation,

package/docs/ONBOARDING_CHAT_CONTRACT.md

@@ -4,6 +4,27 @@ Kira connects the user's installed, unmodified Codex or Claude Code CLI. It does
 
 The setup flow separates account readiness, model choice, context permission, and confirmation. The conversation composer remains visible. It shows the connected CLI, automatic context scope, response state, cancellation, and a new conversation action. Enter sends; Shift+Enter adds a line; composition events never send.
 
+`kira setup` opens the existing Account, Permissions and Ready modal directly
+after the local session and workspace are available. Opening setup does not run
+a model response check, save permissions or start wallet research. Existing
+settings are loaded when setup is reopened. Closing the modal consumes that
+page's setup request, so background polling does not reopen it. Ordinary
+`kira start` keeps the normal workspace entry behavior.
+
+The 0.1.5 selector defaults to Use default model. Codex uses a bounded stdio
+app-server handshake and model/list request; it never starts a thread or turn.
+The subprocess has an eight-second metadata deadline and 256 KB output bound.
+Metadata failures leave the default and Advanced identifier entry available.
+Only installed supported CLI versions are queried. Claude uses its documented
+Sonnet, Opus and Haiku aliases. Every chosen model still requires a deliberate
+generic response test. Vendor account and managed policies may restrict access.
+Workspace settings reuses this modal for both providers and all permissions.
+Fresh setup preselects local history; existing false values remain false.
+History permits reopening chats, without extending model memory or scope.
+No wallet context permits general chat and manual wallet management while
+wallet context and research tools remain unavailable. Any effective model or
+permission change starts a fresh conversation.
+
 Automatic context is none, one explicitly selected registered wallet, or the whole recorded portfolio. An allowlisted projection preserves exact balances, contract and chain identities, timestamps, unknown values, and coverage gaps. It excludes credentials, RPC endpoints, paths, raw errors, jobs, and provider payloads. User-entered text is also sent to the selected provider. Scope, wallet, provider, or model changes start a new conversation and never replay old messages. Only a bounded current conversation is replayed.
 
 Approved wallet context can include validated historical full-balance Mint Club
@@ -53,7 +74,7 @@ in Activity and also appear in the chat tray. Unanalysed wallets show a sidebar
 spinner and open Activity while their first holdings job is active.
 
 History is capped at 100 memory sessions and reads up to 200 validated local
-files. Saving remains opt-in. Memory sessions disappear when the process stops.
+files. Saving is recommended for fresh setup and remains an editable choice. Memory sessions disappear when the process stops.
 A previous session can continue only with exactly the same model and context
 configuration. Reading history does not expand model access. Old saved files
 remain readable. No missing memory-only conversations are reconstructed.
@@ -65,3 +86,15 @@ The receipt is consumed only on success. This does not enable history retention.
 The Kira system voice is concise, composed and practical. It leads with findings
 and preserves evidence, unknown values and signing boundaries. Personality is
 prompt guidance; response quality still depends on the selected model.
+
+## 0.1.5 preparation evidence
+
+The combined settings and model-selection tests cover catalog failures, stale
+responses, custom identifiers, fresh retention defaults, saved opt-outs,
+atomic provider changes, preference preservation, missing keys, cancellation
+and ambiguous receipts. Desktop 1440 × 900 and mobile 390 × 844 checks used an
+empty disposable workspace. Codex 0.158.0 and Claude Code 2.1.293 completed
+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.

package/docs/RELEASE.md

@@ -32,7 +32,7 @@ creation now identifies Open Wallet Standard with its official locally served
 logo and explains encrypted local storage and public-account research. The
 OWS integration and wallet-operation permissions are unchanged.
 
-The next candidate is **0.1.4**. It makes incomplete token discovery visible
+Published **0.1.4** makes incomplete token discovery visible
 before registration and beside wallet holdings, separates disabled discovery
 from missing credentials and provider failures, and offers a connection or
 holdings-refresh action. Registry failures retain bounded redacted examples
@@ -44,10 +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.
 
-Version 0.1.4 requires independent review and operator registry publication.
-It is not yet available from the registry. The showcase HTML animation is
-deployed separately and requires no npm release. Keep published 0.1.2 and
-0.1.3 package bytes immutable. 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,
@@ -69,8 +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
-and 0.1.3 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.
@@ -85,12 +95,12 @@ python3 scripts/prepare-release.py
 ```
 
 `prepare-release.py` scans the package boundary and creates
-`dist/kira-wallet-0.1.4.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.4.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_agent.py

@@ -251,6 +251,7 @@ class AgentStore:
         self.root = Path(root);self.path = self.root/'.kira-agent.json';self.runner=runner;self.detector=detector
         self.lock=threading.RLock();self.turns={};self.active=None;self.epoch=0;self.messages=[];self.conversation=str(uuid.uuid4());self.tested=set();self.config=None;self.workers=[];self.tool_status=None
         self._capabilities=None;self._checked=0
+        self._model_lock=threading.Lock();self._model_cache={}
         self.sessions={};self.started_at=datetime.now(timezone.utc).isoformat();self.updated_at=self.started_at
         if self.path.exists():
             try: self.config=config_input(json.loads(self.path.read_text()),self.root)
@@ -344,6 +345,19 @@ class AgentStore:
             self._capabilities=self.detector();self._checked=time.monotonic()
         with self.lock:return {'config':self.config,'providers':self._capabilities,'conversation_id':self.conversation,'messages':self.messages.copy(),'active_turn':self.active,'tool_status':self.tool_status}
 
+    def models(self, provider, recheck=False):
+        if provider not in PROVIDERS:raise JobError('invalid_provider','Choose Codex or Claude.')
+        with self._model_lock:
+            row=next((row for row in self.status(recheck)['providers'] if row['id']==provider),None)
+            if not row or not row['installed'] or not row['supported']:
+                return {'models':[], 'note':'Install a supported CLI to load model choices. The default model remains available.'}
+            cached=self._model_cache.get(provider)
+            if not recheck and cached and time.monotonic()-cached[0]<60:return cached[1]
+            from kira_models import catalog
+            result=catalog(provider)
+            self._model_cache[provider]=(time.monotonic(),result)
+            return result
+
     def fingerprint(self,config):return hashlib.sha256(json.dumps(config,sort_keys=True).encode()).hexdigest()
 
     def stop(self):

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.')
@@ -232,14 +232,14 @@ def main():
             if args.command=='config':
                 file=Path(args.file).expanduser().resolve()
                 if not file.is_file():raise ValueError('Secret environment file does not exist.')
-                from wallet import ALCHEMY
-                cfg['secret_env_file']=str(file);cfg['discovery']={'provider':'alchemy','key_env':args.key_env,'explorers':True}
-                cfg['rpc']={'mode':'custom','allow_public_fallback':True,
-                    'chains':{str(cid):{'url_env':args.key_env,'alchemy_network':name} for cid,name in ALCHEMY.items()}}
+                from kira_config import provider_config
+                cfg=provider_config(cfg,'alchemy',args.key_env)
+                cfg['secret_env_file']=str(file);cfg['discovery']['explorers']=True
             elif args.command=='discovery':cfg['discovery']={'provider':args.provider,'key_env':args.key_env,'explorers':args.explorers}
             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,9 +16,22 @@ 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):
+    """One settings transition. Preserve explicit fallback and custom overrides."""
+    result={**config,'rpc':{**config['rpc'],'chains':{cid:dict(row) for cid,row in config['rpc']['chains'].items()}},
+            'discovery':{**config['discovery'],'provider':'alchemy' if provider=='alchemy' else 'none','key_env':key_env}}
+    result['rpc']['mode']='custom' if provider=='alchemy' else 'public'
+    if provider=='alchemy':
+        from wallet import ALCHEMY
+        for cid,network in ALCHEMY.items():
+            previous=result['rpc']['chains'].get(str(cid))
+            if not previous or previous.get('alchemy_network'):
+                result['rpc']['chains'][str(cid)]={'url_env':key_env,'alchemy_network':network}
+    return result
+
 def load_config():
     path=config_path()
     if not path.exists():return default_config()
@@ -31,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.')
@@ -84,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():
@@ -92,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

@@ -19,7 +19,7 @@ import uuid
 
 ASSETS = Path(__file__).resolve().parent
 State = Literal['queued', 'running', 'interrupted', 'succeeded', 'partial', 'failed', 'cancelled']
-Operation = Literal['wallet.add','wallet.refresh','prices.refresh','wallet.setTags','settings.rpc','settings.discovery']
+Operation = Literal['wallet.add','wallet.refresh','prices.refresh','wallet.setTags','settings.rpc','settings.discovery','settings.provider']
 TERMINAL = {'succeeded', 'partial', 'failed', 'cancelled', 'interrupted'}
 ADDRESS = re.compile(r'0x[0-9a-fA-F]{40}')
 
@@ -124,10 +124,11 @@ class JobStore:
         if not isinstance(job,dict) or type(job.get('schema_version')) is not int or job.get('schema_version') != 1: raise JobError('unsupported_version', 'Unsupported persisted job version.')
         required={'schema_version','job_id','operation','input','state','attempt','sequence','result','previous_result','key_hash','request_hash','created_at','updated_at','cancel_requested','checkpoint','stage','events','errors','chains'}
         optional={'raw_hash','control_receipts','control_raw','provider_configuration','started_at'}
-        if required-set(job) or set(job)-required-optional or job['job_id']!=job_id or job['checkpoint']!='snapshots/jobs/'+job_id or not isinstance(job['operation'],str) or job['operation'] not in {'wallet.add','wallet.refresh','prices.refresh','wallet.setTags','settings.rpc','settings.discovery'} or not isinstance(job['state'],str) or job['state'] not in TERMINAL|{'queued','running'} or any(type(job[k]) is not int or job[k]<0 for k in ('attempt','sequence')) or type(job['cancel_requested']) is not bool or not isinstance(job['input'],dict) or any(not isinstance(job[k],list) for k in ('events','errors')) or not isinstance(job['chains'],dict):
+        if required-set(job) or set(job)-required-optional or job['job_id']!=job_id or job['checkpoint']!='snapshots/jobs/'+job_id or not isinstance(job['operation'],str) or job['operation'] not in {'wallet.add','wallet.refresh','prices.refresh','wallet.setTags','settings.rpc','settings.discovery','settings.provider'} or not isinstance(job['state'],str) or job['state'] not in TERMINAL|{'queued','running'} or any(type(job[k]) is not int or job[k]<0 for k in ('attempt','sequence')) or type(job['cancel_requested']) is not bool or not isinstance(job['input'],dict) or any(not isinstance(job[k],list) for k in ('events','errors')) or not isinstance(job['chains'],dict):
             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']}[job['operation']]
+            '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.')
@@ -154,8 +155,15 @@ class JobStore:
         return matches[0]
 
     def normalize(self, operation, value):
+        if operation == 'settings.provider':
+            fields(value,['provider','key_env'])
+            if value['provider'] not in ('public','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','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')}
@@ -166,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.')
@@ -399,11 +407,17 @@ 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']
                 config['rpc']=updated
-            else:config['discovery']={**job['input'],'explorers':config['discovery'].get('explorers',False)}
+            elif job['operation']=='settings.discovery':config['discovery']={**job['input'],'explorers':config['discovery'].get('explorers',False)}
+            else:
+                from kira_config import provider_config,secret_values
+                config=provider_config(config,**job['input'])
+                if job['input']['provider']=='alchemy' and not secret_values(config).get(job['input']['key_env']):
+                    raise JobError('connection_key_missing','Kira cannot find the local Alchemy key. Follow the connection guide, then retry. Existing settings are unchanged.')
             atomic(config_path(),config)
             result={'status':'completed','setting':job['operation']};atomic(self.jobs/'results'/(job['job_id']+'.json'),result);return result
         env = {**os.environ, 'KIRA_DATA_DIR': str(self.root), 'KIRA_JOB_ID': job['job_id'], 'KIRA_JOB_SNAPSHOT': job['checkpoint'], 'KIRA_ANALYSIS_FD': str(writer.fileno()), 'PYTHONUNBUFFERED': '1'}