Skip to content

fix(bridge): stop the key backup download from breaking the SDK load on iPhone - #54

Merged
PastaPastaPasta merged 5 commits into
mainfrom
fix/sdk-load-gate
Oct 24, 2026
Merged

PastaPastaPasta merged 5 commits into
mainfrom
fix/sdk-load-gate

Conversation

@PastaPastaPasta

@PastaPastaPasta PastaPastaPasta commented Oct 24, 2026 •

Copy link
Copy Markdown
Member

Why

After #53, creating an identity on testnet fails on iPhones (Safari, confirmed on two phones; Brave on a Mac is fine) with ERR-1006 Identity registration failed / Importing a module script failed. right after the InstantSend lock arrives.

Root cause, reproduced in the iOS 26.5 Simulator against the live site:

  1. The create flow starts downloading the 10 MB EvoSDK chunk and, in the same step, auto-downloads the key backup.
  2. On iOS Safari the backup download raises a "Do you want to download…?" prompt, which cancels every in-flight page load. The SDK chunk fetch is cancelled within ~14 ms.
  3. Safari remembers the failed module import per URL. When registration asks for the chunk after the lock arrives, the import fails immediately with no network request.

Desktop browsers download silently, so they were unaffected. It also explains the "Status unknown" / "Network degraded" badge: testnet Platform status is read through the same cancelled SDK. Ruled out: memory, TLS (Safari accepts the evonode IP certificates), missing JS/wasm features (the SDK chunk is byte-identical to the one before #53).

What changed

  • Load first, then the backup. Every funding flow (create, top-up, send-to-address, on all networks) waits on a "Preparing…" screen until the SDK and Platform chunks are loaded (and, on testnet, the SDK connect, up to 5 s). Only then does it show the deposit address and download the backup. The final backup now downloads after the contract auto-publish. The backup blob URL is kept for 5 minutes so a prompt answered late still works.
  • Cache-busted retries. Browsers remember a failed import per URL, so lazy chunks are retried with a ?retry= query (3 attempts, 0.5 s / 1.5 s backoff). A small Vite plugin supplies each chunk's built URL. A URL is never reused once it has failed. On iOS, a failure within 60 s of a download retries for about a minute and the message points at the download prompt. Failures are logged with the chunk name and shown in Technical Details.
  • Lazy chunks depend only on the already-loaded main bundle. WebKit keeps a failed fetch of a chunk's dependency even across reloads (reproduced with real 503s). A small shared helper is merged into the main bundle, and the build check fails if a lazy chunk ever gains another dependency.
  • Clear failure before funds move. If a chunk still fails, or stalls for 5 minutes, ERR-1017 says a required component failed to load and no funds were sent, with a Reload button.
  • Honest copy after the lock. The screen says the InstantSend lock arrived but the Platform step failed, and offers Retry Registration / Top-up / Send using the proof already held, next to "Use chain lock proof instead". "InstantSend didn't go through" appears only when the lock really never came. Retry is offered only for transient failures (network/transport, no nodes available, timeouts, unconfirmed registration), not for Platform rejections.

Testing

  • tsc --noEmit, vitest run (752 tests), npm run build with the artifact check, and mock-mode Playwright (58/58) pass. Two existing flaky e2e tests (malformed-address, withdraw) fail occasionally; the first also fails on main.
  • iOS 26.5 Simulator (Mobile Safari): reproduced the failure on the unpatched build, then funded create-identity on the fixed builds with the download prompt tapped immediately and left open for ~30 s. Identities verified with proofs; the SDK chunk finished before the prompt and no request was aborted. With the proxy returning 503 for the first SDK request, the retry under ?retry=1… loaded and the flow continued without a reload.
  • Headless Chromium and WebKit (18.4 and 26.5): the busted retry recovers without a reload in all three (Chromium and WebKit 26.5 cache the failed URL, WebKit 18.4 re-fetches); a permanently failing SDK shows ERR-1017 before any deposit address and before any backup download; a blocked Platform broadcast after the lock shows the accurate message and Retry Registration completes; funded happy paths pass. Idle page loads still never fetch the SDK; mainnet's InstantSend path is unchanged.

Not verified

  • iOS versions other than 26.5 and real iPhones, including cellular and switching to a wallet app mid-download.
  • Whether the testnet SDK connect finished before the prompt in the simulator runs (no console access).
  • iPad detection for the iOS-only prompt mode was written but not exercised.
  • Cancelling the chain-lock fallback still hides Retry (pre-existing).

🤖 Generated with Claude Code

Summary by CodeRabbit

  • New Features
    • Added a preparation screen before the deposit step while funding components load.
    • Error screens now provide recovery options tailored to the current step, including retrying eligible submissions and safely reloading before a deposit address is shown.
  • Bug Fixes
    • Improved recovery from temporary component-loading and submission failures, with clearer error details and guidance.
    • Improved key-backup downloads, including on iOS, and kept downloaded files available longer.

PastaPastaPasta and others added 5 commits October 23, 2026 21:11
A failed dynamic import is remembered in the browser's module map for
the page's lifetime (Chromium 136 and WebKit 26.5 both reject a
re-import of the same URL without a request), so one dropped download of
the 10 MB EvoSDK chunk made registration fail for good, with WebKit's
bare "Importing a module script failed.".

- createChunkLoader: memoized, 3 attempts with 0.5/1.5 s backoff;
  retries import the chunk's built URL with a ?retry= query (a new
  module map entry), log each failure with the chunk name, clear the
  memo and throw a ChunkLoadError naming the chunk.
- virtual:chunk-url:<specifier> (Vite plugin) gives the built URL of a
  dynamic-import chunk; emitted with implicitlyLoadedAfterOneOf so the
  chunk graph is unchanged.
- loadPlatformForFunding loads the SDK and platform chunks for the
  funding gate.
- experimentalMinChunkSize merges the 0.24 kB commonjs helper the
  islock and evo-sdk chunks shared into the entry: WebKit keeps a
  failed fetch of such a static dependency across reloads, which no
  retry or reload could recover. The build check now fails if a lazy
  chunk imports anything but the entry.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Owners on iPhone reached "Creating identity..." with the InstantSend
lock in hand and then failed with "Importing a module script failed.":
the EvoSDK chunk was only warmed in the background (failure swallowed)
and first needed after the funds were locked. The error screen then said
"InstantSend didn't go through", which was false.

- Every funding flow (create, top-up, send to address; all networks)
  now waits on a "Preparing…" screen until the SDK and platform chunks
  are loaded. On testnet it also starts the SDK connect and waits for it
  at most 5 s (health indicator semantics unchanged). If a chunk still
  fails after the loader's retries, ERR-1017 explains that a required
  component failed to load, that no funds were sent, and offers Reload.
- After the lock arrived, a failed Platform submission now says so
  ("the InstantSend lock arrived, but ..."), names a chunk that failed
  to load, and offers Retry Registration / Top-up / Send with the proof
  in state, next to the chain lock proof option. "InstantSend didn't go
  through" is kept only for a missing lock.
- Technical Details show the chunk that failed to load.
- Mock-mode e2e: failure injection (window.__e2eMockFailures) drives the
  real retrying loader and the post-lock retry.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
No behaviour change.

- Chunk loader: one retry loop without a lastError/offset dance, the
  retry delays private, CHUNK_LOAD_ATTEMPTS exported for the e2e mock,
  instanceof instead of an isChunkLoadError wrapper.
- Error screen: the hint and label choices move into small functions
  instead of nested ternaries.
- Mock failure injection: one consume helper; the e2e helpers live at
  file scope.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…n iOS

Root cause (reproduced in the iOS 26.5 Simulator): the create flow fired
the EvoSDK warmup and, in the same step, the automatic key backup
download. On iOS Safari that download asks "Do you want to download
...?", which cancels the page's in-flight loads and fails new ones until
answered. The SDK chunk import was cancelled and Safari remembered the
failure, so registration failed after the InstantSend lock arrived.

- The deposit-step backup now always follows the funding gate (SDK and
  platform chunks in memory, testnet connect awaited up to 5 s), and the
  testnet connect is redone on focus or after 15 s in case the prompt
  cancelled it.
- The final backup is downloaded after the contract auto-publish, not
  before it.
- The backup's blob URL lives 5 minutes, so a prompt answered late still
  downloads it.
- A chunk load failing within a minute of a download retries for about a
  minute, and the error explains the browser prompt.

Review fixes:
- Busted retry URLs are never reused across rounds (a second round
  would otherwise fail from the module map without a request), and
  failures other than a failed download are not retried.
- The gate gives up after 120 s with the Reload error instead of
  "Preparing..." forever.
- Retry Registration / Top-up / Send is offered only for transient
  failures (transport, load, unconfirmed); a Platform rejection keeps
  only the chain lock proof option.
- The build check verifies the chunk URLs in the entry name real
  dynamic import targets.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…prompt mode

Review follow-ups:
- Retry Registration / Top-up / Send now matches only transient texts:
  fetch/load failures, "no available addresses", gRPC Unavailable or
  Deadline exceeded, client timeouts (PlatformOperationTimeoutError) and
  the devnet polling window. It no longer goes through
  isRetryableError, whose bare "500"/"429"/"timeout" substrings also
  matched Platform rejections.
- The gate times out after 5 min (7 MB gzipped at about 200 kbit/s)
  instead of 120 s, and names the chunk that stalled.
- The long backoff and the download-prompt copy apply only on iOS (all
  WebKit), where the download prompt blocks loads.
- Mock-mode create/top-up download the backup after the gate, as the
  real flows do; e2e asserts the download comes after the retried SDK
  load and never happens when the gate fails.
- Small cleanups: withChunkTimeout, warmFundingConnect,
  DEFAULT_CHUNK_LOAD_ATTEMPTS, mock submission steps in one switch,
  JSDoc placement.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@coderabbitai

coderabbitai Bot commented Oct 24, 2026 •

Copy link
Copy Markdown

Review in Change Stack →

No actionable comments were generated in the recent review.

Recent review info
Run configuration
  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: eb9f1318-ef1d-4d11-b799-dbad3c49bbbe
Commits

Reviewing files that changed from the base of the PR and between 4e909fe and 3efeb04.

Files selected for processing: 16
  • e2e/deterministic.spec.ts
  • scripts/check-build-artifacts.mjs
  • src/config/vite-chunk-url.ts
  • src/main.ts
  • src/platform/chunk-loader.test.ts
  • src/platform/chunk-loader.ts
  • src/platform/loaders.test.ts
  • src/platform/loaders.ts
  • src/platform/sdkModule.ts
  • src/ui/components.error-recovery.test.ts
  • src/ui/components.ts
  • src/ui/state.error-recovery.test.ts
  • src/ui/state.ts
  • src/vite-env.d.ts
  • vite.config.ts
  • vitest.config.ts
Files with no reviewable changes: 1
  • src/platform/loaders.test.ts

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

Walkthrough

The change adds retrying chunk loaders and a funding preparation gate before deposit steps. It also adds recovery rules and UI actions for component-load and Platform submission failures, with tests covering failure and retry paths.

Changes: Funding preparation and recovery

Layer / File(s) Summary
Chunk loading and build validation
src/platform/chunk-loader.ts, src/platform/loaders.ts, src/platform/sdkModule.ts, src/config/vite-chunk-url.ts, src/vite-env.d.ts, vite.config.ts, vitest.config.ts, scripts/check-build-artifacts.mjs, src/platform/chunk-loader.test.ts, src/platform/loaders.test.ts
Chunk imports now share in-flight loads, retry eligible failures, and use cache-busted URLs when available. Build configuration emits virtual chunk URLs, and the artifact check validates emitted JavaScript imports and EvoSDK URLs.
Funding preparation and identity completion
src/main.ts
Funding flows load Platform components before connecting the SDK and continuing to deposit steps. Identity creation paths use completeIdentityCreation for state updates, contract publication, and final key-backup downloads.
Submission recovery and error display
src/ui/state.ts, src/ui/components.ts, src/main.ts, e2e/deterministic.spec.ts, src/ui/state.error-recovery.test.ts, src/ui/components.error-recovery.test.ts
The state layer determines retry eligibility and reload safety. Error screens display recovery controls and failed chunk details. Mock flows and tests exercise component-load and submission failures, including retries.

Priority: Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Bug fix

Sequence Diagram(s)

sequenceDiagram
  participant FundingFlow
  participant loadPlatformForFunding
  participant ChunkLoader
  participant FundingSDK
  participant DepositUI
  FundingFlow->>loadPlatformForFunding: load EvoSDK and Platform modules
  loadPlatformForFunding->>ChunkLoader: load modules with timeouts
  ChunkLoader-->>loadPlatformForFunding: return loaded modules or load error
  FundingFlow->>FundingSDK: connect after Platform chunks load
  FundingSDK-->>FundingFlow: return connection result or 5-second timeout
  FundingFlow->>DepositUI: continue to deposit step
Loading

Possibly related PRs

Merge Risk: Minimal · up to 3efeb

No actionable merge-blocking issue was established. The change is ready to merge after normal checks.

Pre-merge checks: Passed 4 · Failed 1

Failed Failed checks: 1 warning

Check name Status Explanation Resolution
Docstring Coverage Warning Docstring coverage is 59.57% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 47 functions across 15 files. Write docstrings for the functions missing them to satisfy the coverage threshold.
Passed Passed checks: 4 passed
Check name Status Explanation
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check Passed The title clearly states the iOS key-backup download issue that the pull request addresses. It is specific and related to the main change.
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Finishing Touches: 💡 1
📝 Generate docstrings: 💡
  • Commit to this branch
  • Create a new PR
🧪 Generate unit tests (beta)
  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@PastaPastaPasta
PastaPastaPasta merged commit 05baedb into main Oct 24, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant