TAT-3176 Report

Summary

Fixed wrapped KEYRING_LOCKED classification in HyperLiquid perps setup paths. The provider now walks the error cause chain so SDK-wrapped signing failures are treated as retry-later keyring-lock states instead of generic failures.

Root cause

HyperLiquidWalletService.#signTypedMessage throws KEYRING_LOCKED when the keyring is unavailable. The HyperLiquid SDK wraps that as Failed to sign typed data with viem wallet and stores the original error in cause, but HyperLiquidProvider compared only ensureError(error).message at the unified-account, builder-fee, and referral catches. That missed wrapped keyring-lock errors and let them fall through to failed analytics/cache/Sentry paths.

Reproduction commit

Marker commit: b9ff93030c1b7ec4250e5741a97bf35d47119cfd

Metro excerpt:

DEBUG  [PR-local] BUG_MARKER: wrapped KEYRING_LOCKED reached generic Sentry logger

Changes

• app/controllers/perps/utils/errorUtils.ts: added isKeyringLockedError, a cycle-safe cause-chain classifier.
• app/controllers/perps/providers/HyperLiquidProvider.ts: replaced three direct message equality checks with the cause-chain classifier.
• app/controllers/perps/utils/errorUtils.test.ts: covered direct, wrapped, and cyclic error cases.
• app/controllers/perps/providers/HyperLiquidProvider.test.ts: covered wrapped keyring-lock behavior in unified-account, builder-fee, and referral setup paths.

Test plan

• yarn lint && NODE_OPTIONS='--max-old-space-size=8192' yarn lint:tsc && yarn format:check
• yarn jest app/controllers/perps/utils/errorUtils.test.ts app/controllers/perps/providers/HyperLiquidProvider.test.ts --no-coverage
• yarn coverage:analyze --files app/controllers/perps/utils/errorUtils.ts app/controllers/perps/providers/HyperLiquidProvider.ts
• bash scripts/perps/agentic/validate-recipe.sh .task/fix/tat-3176-0512-222920/artifacts/ --skip-manual

Feature: Wrapped KEYRING_LOCKED handling

  Scenario: wrapped keyring lock is retried later
    Given HyperLiquid setup receives an SDK error with cause.message KEYRING_LOCKED
    When the provider classifies the setup error
    Then the retry-later branch is used
    And the generic Sentry failure branch is not used

Evidence

• .task/fix/tat-3176-0512-222920/artifacts/recipe.json
• .task/fix/tat-3176-0512-222920/artifacts/recipe-baseline.json
• .task/fix/tat-3176-0512-222920/artifacts/recipe-coverage.md
• .task/fix/tat-3176-0512-222920/artifacts/evidence-manifest.json
• State-only fix; no before/after screenshots or videos are required.

Ticket

TAT-3176: https://consensyssoftware.atlassian.net/browse/TAT-3176

Self-Review Fixes

• app/controllers/perps/providers/HyperLiquidProvider.test.ts — moved wrapped KEYRING_LOCKED builder-fee coverage out of the skipped global-cache describe and into an executed public placeOrder path assertion.
• .task/fix/tat-3176-0512-222920/artifacts/recipe.json — changed the recipe to load the bundled app/controllers/perps/utils/errorUtils.ts module through Metro and call the real isKeyringLockedError export instead of duplicating classifier logic inline.
• app/controllers/perps/utils/errorUtils.ts:1 — updated the module header so it accurately describes both generic error helpers and Perps error classification helpers.

Workflow Diagram (Mermaid)

flowchart TD
ac1["ac1-assert-wrapped-keyring-locked"]
done["done"]
ac1 --> done

E2E Test Selection:
The changes are scoped to the Perps controller layer:

1. errorUtils.ts: Adds isKeyringLockedError() — a new utility that walks the error cause chain to detect KEYRING_LOCKED errors even when wrapped by SDK layers (e.g., viem wallet signing failures).

2. HyperLiquidProvider.ts: Replaces direct string comparison with isKeyringLockedError() in three catch blocks (ensureUnifiedAccountEnabled, ensureBuilderFeeApproval, ensureReferralSet). This is a bug fix: previously, SDK-wrapped KEYRING_LOCKED errors were not detected, causing retry caches to be incorrectly populated. Now the full error cause chain is checked.

3. Test files: Unit tests validating the new utility and the HyperLiquidProvider behavior with wrapped errors.

Tag rationale:

• SmokePerps: Directly affected — HyperLiquidProvider is the core perps trading provider. The fix affects order placement flows (builder fee approval, referral setup, unified account enabling) when the keyring is locked.
• SmokeWalletPlatform: Required by SmokePerps description (Perps is a section inside Trending tab).
• SmokeConfirmations: Required by SmokePerps description (Add Funds deposits are on-chain transactions).

No changes to UI components, navigation, shared infrastructure, or other controllers. Risk is medium because the fix touches core trading flow error handling in the perps provider.

Performance Test Selection:
No UI rendering changes, no list components, no state management changes, no app startup changes. The change is purely error handling logic (isKeyringLockedError utility) in the perps provider catch blocks. No performance impact expected.