kira-wallet 0.1.8 → 0.1.10

package/README.md

@@ -47,7 +47,7 @@ include the same package and its checksum.
    ERC20 discovery. Free token sources have limited coverage; incomplete coverage
    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 discovery on supported networks. First balances appear before detailed research finishes.
+   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.
 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/THIRD_PARTY_NOTICES.md

@@ -34,3 +34,12 @@ chain/contract identities from Uniswap default-token-list at commit
 583cb696cc15778536fe0ddd416de5bd81be2023. The upstream references retain
 GPL-3.0 terms in `sources/TOKEN_LIST_LICENSE.txt`. Per-contract provenance is
 recorded in the catalog. No upstream executable code or artwork is included.
+
+
+Free token discovery uses [Etherscan keyless MCP](https://docs.etherscan.io/build-with-ai/mcp)
+and [Routescan](https://routescan.io/docs). Data is provided by those services,
+subject to their availability and usage limits. Their data does not establish
+token safety, current balance, value or an exhaustive inventory. No service SDK
+or credential is distributed. Selected new known identities use issuer documents,
+PancakeSwap integration references and freshly verified on-chain metadata; their
+per-contract provenance is in the catalog.

package/chain_lifecycle.py

@@ -0,0 +1,44 @@
+"""Reviewed notices are separate from reachability and token discovery."""
+REVIEWED_ON='2026-10-11'
+# A retrieved network reference is not a live health or perpetual-active claim.
+REFERENCES={
+    1:'https://ethereum.org/developers/docs/networks/',11155111:'https://ethereum.org/developers/docs/networks/',
+    8453:'https://docs.base.org/get-started/connect-to-base',84532:'https://docs.base.org/get-started/connect-to-base',
+    81457:'https://docs.blast.io/building/network-information',168587773:'https://docs.blast.io/building/network-information',
+    10:'https://docs.optimism.io/op-stack/introduction/op-stack',42161:'https://docs.arbitrum.io/chain-info',
+    43114:'https://build.avax.network/docs/primary-network',43113:'https://build.avax.network/docs/primary-network',
+    137:'https://docs.polygon.technology/pos/reference/rpc-endpoints',
+    56:'https://docs.bnbchain.org/bnb-smart-chain/developers/networkinfo/',
+    109:'https://docs.shib.io/get-started/shibarium',157:'https://docs.shib.io/get-started/shibarium',
+    7560:'https://docs.cyber.co/network-info/overview',111557560:'https://docs.cyber.co/network-info/overview',
+    5112:'https://docs.ham.fun/',8217:'https://docs.kaia.io/build/get-started/foundation-setup/',
+    130:'https://developers.uniswap.org/docs/unichain',7777777:'https://docs.zora.co/zora-network/network',
+    33139:'https://docs.apechain.com/chain-info',177:'https://docs.hsk.xyz/docs/Build-on-HashKey-Chain/network-info',
+    4663:'https://docs.robinhood.com/chain/connecting/',54176:'https://docs.over.network/',
+}
+UNAVAILABLE_REFERENCES={56,7777777,33139,54176}
+NOTICES={
+    666666666:{'status':'retired','verified':True,'reviewed_on':REVIEWED_ON,
+        'notice_url':'https://www.alchemy.com/docs/reference/degen-deprecation-notice',
+        'network_shutdown_date':None,'provider_support_ended_on':'2026-08-31',
+        'note':'Alchemy describes Degen L3 as shut down. Its provider support ended August 31. The exact network shutdown date is not independently established. Base DEGEN is a separate token.'},
+    5112:{'status':'retirement_reported','verified':False,'reviewed_on':REVIEWED_ON,
+        'notice_url':None,'reference_url':'https://docs.ham.fun/',
+        'note':'The operator reports Ham has stopped. A primary closure notice has not been located. Failed reads do not establish closure.'},
+}
+
+
+def lifecycle(chain_id):
+    state=dict(NOTICES.get(chain_id,{'status':'unconfirmed','verified':False,
+        'notice_url':None,'note':'No verified retirement notice is recorded. Connectivity and discovery are separate observations.'}))
+    state.update(reference_url=REFERENCES.get(chain_id,state.get('reference_url')),
+        reviewed_on=REVIEWED_ON if chain_id in REFERENCES or chain_id in NOTICES else None,
+        audit_result='reference_unavailable' if chain_id in UNAVAILABLE_REFERENCES else 'reference_retrieved' if chain_id in REFERENCES else 'notice_reviewed' if chain_id in NOTICES else 'not_reviewed')
+    if chain_id==8217:
+        state['provider_notice']={'provider':'The Graph','support_ended_on':'2026-08-31','url':'https://docs.kaia.io/build/tools/indexers/','note':'Indexer support ended. This does not establish network retirement.'}
+    return state
+
+
+def retired(chain_id):
+    state=lifecycle(chain_id)
+    return state['status']=='retired' and state['verified'] is True

package/docs/AGENT_TOOLS.md

@@ -82,6 +82,14 @@ on-chain checkpoint status. Deferred candidates and pending networks are not
 failed reads or zero holdings. Historical observations cannot establish current
 execution, transfers or realized profit.
 
+`records_read` executes one bounded plan of up to eight declared read tools.
+Each child has its own host receipt. Literal JSON read requests are matched
+against their actual arguments, including chain and contract. Full inventory
+requests require contiguous delivered pages through `next_offset: null`.
+Failed or undelivered pages remain unread, with retry arguments in the turn's
+`read_completion`. Automatic context is not a requested tool receipt. This
+bounded check does not verify every semantic requirement in natural prose.
+
 rpc_status pending means a network has not yet been researched. It does not
 prove an RPC outage. For a curve comparison, match chain and contract and
 compare reserve, supply, next-mint price and royalty observations. A newer

package/docs/ALCHEMY_SETUP.md

@@ -1,8 +1,9 @@
 # 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.
+common token contracts and the Mint Club registry, and uses keyless transfer
+discovery on supported networks. Unfinished history and other ERC20 holdings
+may still 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

package/docs/FREE_RPC.md

@@ -7,7 +7,10 @@ effort and can throttle requests or omit historical state.
 The reviewed default catalog adds alternatives on Ethereum, Base, BNB Chain,
 Polygon, Arbitrum and Optimism. PublicNode is the initial preference. Reserves
 are selected per chain rather than downloaded from an untrusted runtime list.
-The other supported networks retain their existing endpoints.
+Shibarium and Puppynet use the current official Shib endpoints. Cyber mainnet
+adds the official Superchain registry endpoint. Unverified replacements are
+never accepted just because an endpoint returns HTTP 200. Some configured
+networks can remain unavailable; their missing balances stay unknown.
 
 ## Request behavior
 
@@ -110,3 +113,82 @@ Primary references: [EIP-1898](https://eips.ethereum.org/EIPS/eip-1898),
 [Circle contracts](https://developers.circle.com/stablecoins/usdc-contract-addresses),
 [Tether contracts](https://tether.to/en/supported-protocols/),
 [Uniswap Arbitrum deployments](https://developers.uniswap.org/docs/protocols/v3/deployments/v3-arbitrum-deployments).
+
+## Recorded route evidence and remaining limits
+
+Chain coverage includes `rpc_routes`: bounded aggregate logical endpoint outcomes
+with public/custom class, endpoint index, method, outcome and count. Failures
+can include HTTP or RPC error codes. A successful read can follow failed public
+attempts; configuring public first does not prove every read was public.
+Cooldown skips, queue timeouts and successes are distinct. The receipt contains
+no endpoint URLs, keys, request arguments or balances. Cached checkpoints retain
+their original evidence and routes; a resume is not a fresh observation.
+
+A live October 10 check identified DNS failures on the old Shib endpoints,
+Ham, Over and Cyber testnet. Current official Shib endpoints returned the correct
+chain identities and supported hash-qualified balance reads. Cyber mainnet's
+registry endpoint also passed. The official Cyber testnet replacement failed
+certificate validation, so it was not added. Ham and Over have no verified
+replacement in this catalog. This is an observation, not a claim that their
+chains permanently stopped. Their failed checks remain visible.
+
+Base public balance reads work independently of arbitrary token discovery.
+In published 0.1.9, the keyless Base inventory was selected common contracts and Mint Club. The next candidate adds the Etherscan transfer path below.
+Blockscout's current documentation deprecates per-instance APIs in favor of its
+keyed PRO API. Kira does not promise keyless Base enumeration through that route.
+The former 1RPC Base reserve returned HTTP 410 during block lookup and was
+removed. PublicNode and dRPC remain verified Base candidates. The official Base
+public endpoint returned HTTP 403 in this test and was not silently substituted.
+
+Sources: [Shib network setup](https://docs.shib.io/get-started/deploy-contracts),
+[Superchain registry](https://github.com/ethereum-optimism/superchain-registry/blob/main/chainList.toml),
+[Ham network information](https://docs.ham.fun/docs/network-information/),
+[Blockscout API migration](https://docs.blockscout.com/devs/apis).
+
+
+## Keyless transfer candidates
+
+Kira uses [Etherscan keyless MCP](https://docs.etherscan.io/build-with-ai/mcp)
+for ERC20 transfer identities on Ethereum, Base, Optimism, Arbitrum, Polygon
+and BNB Smart Chain. This backend adapter needs no model MCP configuration,
+API key, paid relay or shared credentials. Routescan remains available on
+Avalanche and Blast. Standard RPC verifies each candidate at a canonical
+pinned block. Transfer amounts never become wallet balances.
+
+Each request scans at most three 100-record pages within the research budget.
+A window ends at a block before a timestamp two minutes behind the local clock,
+allowing for explorer indexing lag. Its block bounds and next page are saved
+per wallet and chain. A later refresh continues unfinished history. Once a
+window finishes, subsequent refreshes recheck a 2,048-block overlap, scan new
+blocks and retain earlier candidate identities. A deeper reorg or older indexer
+backfill can still omit identities. While older history is pending, one fresh
+bounded page can find new receipts without replacing its saved frontier.
+A 100-page or 10,000-contract safety limit remains
+explicitly incomplete. Provider backfills, history limits, indexing lag and
+unsupported networks can still omit tokens. A finished window is not proof
+of a complete inventory. No majority-coverage promise is made.
+
+The shared local request lane conservatively paces tool calls every two seconds.
+HTTP 429 pauses that lane. It does not rotate accounts or evade provider limits.
+Sessions stay in process memory. Saved evidence contains candidate contracts
+and window facts, never MCP session IDs, credentials or transfer-derived balances.
+No liquidity or dollar-value filter removes candidate identities. Spam transfers
+can introduce irrelevant candidates. Only positive RPC balances enter holdings.
+
+Earlier positive holdings, common known contracts and Mint Club identities
+supplement candidate discovery. Targeted suspicious zeros receive up to eight
+direct and qualified peer checks per chain, at the same pinned hash. Conflicting
+or unavailable checks remain unknown. Ordinary zero-heavy registry scans do
+not receive an unbounded peer fan-out.
+
+## Network lifecycle
+
+A verified retirement notice removes a network from new default research and
+current valuation. Historical assets and timestamps remain available.
+Connectivity, stale observed heads, token discovery and provider support loss
+remain separate facts. Ham has an operator retirement report with no verified
+primary closure notice. It is labelled explicitly, without recommending
+Alchemy as a verified recovery path. Degen L3 is absent from the current catalog;
+its reviewed Alchemy notice is separate from Base DEGEN. A responding archive
+endpoint does not make a retired chain current. No bridge or migration outcome
+is promised.

package/docs/ONBOARDING_CHAT_CONTRACT.md

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

package/docs/RELEASE.md

@@ -94,12 +94,12 @@ python3 scripts/prepare-release.py
 ```
 
 `prepare-release.py` scans the package boundary and creates
-`dist/kira-wallet-0.1.8.tgz`. The ignored `dist/release.json` records its source
+`dist/kira-wallet-0.1.10.tgz`. The ignored `dist/release.json` records its source
 commit, SHA-256 and member count. It never publishes. After reviewing that
 manifest, the operator's final command from the project root is:
 
 ```sh
-npm publish ./dist/kira-wallet-0.1.8.tgz --access public
+npm publish ./dist/kira-wallet-0.1.10.tgz --access public
 ```
 
 Use the operator's npm account and complete authentication or OTP personally.
@@ -123,9 +123,9 @@ with untouched settings fields while preserving edited drafts.
 
 The operator published **0.1.7** on October 9, 2026. Its archive is immutable.
 
-## Proposed 0.1.8 behavior
+## Published 0.1.8 behavior
 
-The next archive is **0.1.8**, unpublished until the operator runs the command.
+The operator published **0.1.8** on October 9, 2026. Its archive is immutable.
 It queues local connection imports during research, lets settings and price
 updates preempt enrichment, preserves explicit cancellation, and checkpoints
 wallet balance batches and market verification at fixed blocks. A 180-second
@@ -169,3 +169,45 @@ establish that native extension acceptance passed. Those actions still require
 the operator's device handoff. Signing and trading remain outside Kira. Human-submitted OWS creation stores an encrypted wallet in the separate local OWS vault.
 
 See [current UI evidence](https://github.com/realproject7/kira-wallet/blob/codex/kira-release/docs/KIRA_UI_REFINEMENT.md).
+
+## Proposed 0.1.9 behavior
+
+Version 0.1.9 permits a saved report's price update during detailed research,
+with duplicate queued/running price feedback and existing automatic continuation.
+Network empty states distinguish pending coverage, incomplete checks, completed
+empty records and actual filter exclusion. Native facts include full-inventory
+category valuation and explicit unknown activity causes. Public RPC configuration
+updates verified Shib/Cyber routes and removes a failed Base reserve. Sanitized
+route outcomes distinguish public-only acceptance from custom fallback. Bounded
+route telemetry retains aggregate outcomes when detailed records reach their cap.
+Compact agent facts retain historical quote presence even when outputs are deferred.
+Snapshot comparisons provide exact full-comparison and per-chain counts before
+pagination so native agents do not need to tally large position pages manually.
+
+Publication remains an operator action. Post-publication acceptance uses two
+clean installations of the same verified registry bytes: public/free only first,
+then a clean reinstall with authorized Alchemy discovery and public-first backup.
+Each lane begins without previous holdings, identity caches or RPC health.
+Compare exact chain/contract identities, observations, coverage, route classes,
+failures and runtime. Separate changed observation times from discovery effects.
+The procedure does not treat partial free discovery as exhaustive or stale spot
+sums as wealth floors. Private wallets, financial screenshots and local tickets
+stay outside the package and public review.
+
+
+## Next candidate: 0.1.10
+
+This candidate adds saved keyless ERC20 transfer discovery on six core chains,
+canonical RPC balance verification and explicit unfinished-history feedback.
+It fixes public-first cold qualification budgeting, exposes sanitized saved
+provider routes and authoritative coverage counts to native tools, and adds
+bounded read plans with individual completion receipts. Failed account probes
+are distinct from unsupported versions. Reviewed lifecycle notices and targeted
+suspicious-zero checks preserve unknown and historical observations.
+
+Publication is operator-only. Prepare the archive from the final reviewed clean
+commit, run the required install and public checks, and test that exact archive
+in isolated public-only and Alchemy auxiliary workspaces. The personal published
+0.1.9 app and archive remain intact. The final release manifest records the
+candidate source commit, digest and package members. Do not publish an
+unreviewed development pack.