feat: add Solana nested ATA recovery to wallet-recovery-wizard

Adds a new "SOL Nested ATA" / "TSOL Nested ATA" flow under the
Non-BitGo Recovery section of the wizard, allowing clients to
self-serve recovery of SPL tokens stuck in a nested Associated
Token Account without running scripts manually.

- New NestedATAForm with all required keycard and ATA address fields
- New recoverNestedAta IPC command wiring Sol.recoverNestedAta()
- Coin metadata entries for solNestedATA / tsolNestedATA
- Success page now shows txId and Solscan link when available
- Bumps node engine constraint to >=20.10.0 and pins uuid to ^8.3.2
  to resolve ESM/CJS conflict in @solana/buffer-layout-utils

TICKET: COINS-148

Author: bhavidhingra

e2e/sol/nested-ata-recovery.spec.ts

@@ -0,0 +1,93 @@
+import { test, expect, _electron as electron } from '@playwright/test';
+import type { ElectronApplication, Page } from '@playwright/test';
+
+const MOCK_TX_ID = 'mockTxId1234567890abcdef';
+
+function stubNestedAtaHandlers(app: ElectronApplication) {
+  return app.evaluate(
+    ({ ipcMain }, txId) => {
+      for (const ch of ['setBitGoEnvironment', 'recoverNestedAta'])
+        ipcMain.removeHandler(ch);
+      ipcMain.handle('setBitGoEnvironment', () => undefined);
+      ipcMain.handle('recoverNestedAta', () => ({ txId }));
+    },
+    MOCK_TX_ID
+  );
+}
+
+test.describe('Solana nested ATA recovery', () => {
+  let app: ElectronApplication;
+  let page: Page;
+
+  test.beforeEach(async () => {
+    app = await electron.launch({ args: ['.', '--no-sandbox'] });
+    page = await app.firstWindow();
+    await page.waitForSelector('#root');
+    await stubNestedAtaHandlers(app);
+  });
+
+  test.afterEach(async () => {
+    await app.close();
+  });
+
+  test('renders NestedATAForm for solNestedATA coin', async () => {
+    await page.evaluate(() => {
+      window.location.hash = '/prod/non-bitgo-recovery/solNestedATA';
+    });
+
+    await page.waitForSelector('[name="nestedAtaAddress"]');
+
+    await expect(page.locator('[name="userKey"]')).toBeVisible();
+    await expect(page.locator('[name="backupKey"]')).toBeVisible();
+    await expect(page.locator('[name="bitgoKey"]')).toBeVisible();
+    await expect(page.locator('[name="walletPassphrase"]')).toBeVisible();
+    await expect(page.locator('[name="recoveryDestination"]')).toBeVisible();
+    await expect(page.locator('[name="nestedAtaAddress"]')).toBeVisible();
+    await expect(page.locator('[name="ownerAtaAddress"]')).toBeVisible();
+    await expect(page.locator('[name="tokenMintAddress"]')).toBeVisible();
+  });
+
+  test('shows validation errors when submitted empty', async () => {
+    await page.evaluate(() => {
+      window.location.hash = '/prod/non-bitgo-recovery/solNestedATA';
+    });
+    await page.waitForSelector('[name="nestedAtaAddress"]');
+
+    await page.click('button[type="submit"]');
+
+    // Formik marks fields as touched on submit — the Textarea component signals
+    // errors via tw-border-red-500 (not aria-invalid)
+    await expect(page.locator('[name="userKey"]')).toHaveClass(/tw-border-red-500/);
+    await expect(page.locator('[name="nestedAtaAddress"]')).toHaveClass(/tw-border-red-500/);
+  });
+
+  test('completes recovery and shows txId on success page', async () => {
+    await page.evaluate(() => {
+      window.location.hash = '/prod/non-bitgo-recovery/solNestedATA';
+    });
+    await page.waitForSelector('[name="nestedAtaAddress"]');
+
+    await page.fill('[name="userKey"]',            '{"iv":"abc","v":1,"iter":10000,"ks":256,"ts":64,"mode":"ccm","adata":"","cipher":"aes","ct":"encryptedUserKey"}');
+    await page.fill('[name="backupKey"]',           '{"iv":"def","v":1,"iter":10000,"ks":256,"ts":64,"mode":"ccm","adata":"","cipher":"aes","ct":"encryptedBackupKey"}');
+    await page.fill('[name="bitgoKey"]',            'xpub661MyMwAqRbcGHoJePkfLFqgzNBjqAqMjZaRVPMd3su2mTJ7HJQNFVkBkzVHBG7yWVZvLgXSZDmDj8mqqVFnzWijVhKanGj6ygSWfzFQ6eB');
+    await page.fill('[name="walletPassphrase"]',    'test-passphrase-123');
+    await page.fill('[name="recoveryDestination"]', '7YbcLmVorrH7KCKMj38rFidsruisWi2CmvCTs4cygf8K');
+    await page.fill('[name="nestedAtaAddress"]',    'FGuZSBhtreqSUsE86xokyjKz2i8VBtJzy6uMXXKyGHug');
+    await page.fill('[name="ownerAtaAddress"]',     'Zfm98ZpVafydhFTYcsY6bHgubhB4cFgWFvbdEJxYhTA');
+    await page.fill('[name="tokenMintAddress"]',    'ZBCNpuD7YMXzTHB2fhGkGi78MNsHGLRXUhRewNRm9RU');
+
+    await page.click('button[type="submit"]');
+
+    await page.waitForURL(/non-bitgo-recovery\/solNestedATA\/success/, { timeout: 10_000 });
+    await expect(page.getByText(MOCK_TX_ID)).toBeVisible();
+    await expect(page.getByText('View on Solscan')).toBeVisible();
+  });
+
+  test('renders NestedATAForm for tsolNestedATA coin (testnet)', async () => {
+    await page.evaluate(() => {
+      window.location.hash = '/test/non-bitgo-recovery/tsolNestedATA';
+    });
+    await page.waitForSelector('[name="nestedAtaAddress"]');
+    await expect(page.locator('[name="nestedAtaAddress"]')).toBeVisible();
+  });
+});

electron/main/index.ts

@@ -458,6 +458,12 @@ async function createWindow() {
     );
   });
 
+  ipcMain.handle('recoverNestedAta', async (event, coin, parameters) => {
+    const baseCoin = sdk.coin(coin) as Sol;
+    const openSSLBytes = loadWebAssembly().buffer;
+    return await baseCoin.recoverNestedAta({ ...parameters, openSSLBytes });
+  });
+
   ipcMain.handle('broadcastTransaction', async (event, coin, parameters) => {
     const baseCoin = sdk.coin(coin);
     return await baseCoin.broadcastTransaction(parameters);

electron/preload/index.ts

@@ -81,6 +81,21 @@ type Commands = {
   showSaveDialog(
     options: Electron.SaveDialogOptions
   ): Promise<Electron.SaveDialogReturnValue>;
+  recoverNestedAta(
+    coin: string,
+    parameters: {
+      userKey: string;
+      backupKey: string;
+      bitgoKey: string;
+      walletPassphrase: string;
+      recoveryDestination: string;
+      nestedAtaAddress: string;
+      ownerAtaAddress: string;
+      tokenMintAddress: string;
+      apiKey?: string;
+      seed?: string;
+    }
+  ): Promise<{ txId?: string }>;
   recover(
     coin: string,
     parameters: RecoverParams & {
@@ -205,6 +220,9 @@ const commands: Commands = {
   showSaveDialog(options) {
     return ipcRenderer.invoke('showSaveDialog', options);
   },
+  recoverNestedAta(coin, parameters) {
+    return ipcRenderer.invoke('recoverNestedAta', coin, parameters);
+  },
   recover(coin, parameters) {
     return ipcRenderer.invoke('recover', coin, parameters);
   },

eslint.config.mjs

@@ -21,6 +21,7 @@ export default tseslint.config(
       'eslint.config.mjs',
       // Fails at the parser level — must use ignores, not per-file overrides
       'src/components/Title/Title.test.tsx',
+      'src/containers/NonBitGoRecoveryCoin/NestedATAForm.test.tsx',
     ],
   },
 

src/containers/NonBitGoRecoveryCoin/NestedATAForm.test.tsx

@@ -0,0 +1,122 @@
+import { render, screen, fireEvent, waitFor } from '@testing-library/react';
+import { MemoryRouter } from 'react-router-dom';
+import { vi } from 'vitest';
+import { NestedATAForm } from './NestedATAForm';
+
+function renderForm(onSubmit = vi.fn()) {
+  const result = render(
+    <MemoryRouter>
+      <NestedATAForm onSubmit={onSubmit} />
+    </MemoryRouter>
+  );
+  const q = (name: string) =>
+    result.container.querySelector<HTMLElement>(`[name="${name}"]`)!;
+  return { ...result, q };
+}
+
+function fillValidForm(q: (name: string) => HTMLElement) {
+  fireEvent.change(q('userKey'), {
+    target: { value: '{"iv":"abc","ct":"encryptedUserKey"}' },
+  });
+  fireEvent.change(q('backupKey'), {
+    target: { value: '{"iv":"def","ct":"encryptedBackupKey"}' },
+  });
+  fireEvent.change(q('bitgoKey'), {
+    target: { value: 'xpubBitGoKey' },
+  });
+  fireEvent.change(q('walletPassphrase'), {
+    target: { value: 'test-passphrase' },
+  });
+  fireEvent.change(q('recoveryDestination'), {
+    target: { value: '7YbcLmVorrH7KCKMj38rFidsruisWi2CmvCTs4cygf8K' },
+  });
+  fireEvent.change(q('nestedAtaAddress'), {
+    target: { value: 'FGuZSBhtreqSUsE86xokyjKz2i8VBtJzy6uMXXKyGHug' },
+  });
+  fireEvent.change(q('ownerAtaAddress'), {
+    target: { value: 'Zfm98ZpVafydhFTYcsY6bHgubhB4cFgWFvbdEJxYhTA' },
+  });
+  fireEvent.change(q('tokenMintAddress'), {
+    target: { value: 'ZBCNpuD7YMXzTHB2fhGkGi78MNsHGLRXUhRewNRm9RU' },
+  });
+}
+
+describe('NestedATAForm', () => {
+  it('renders all required fields', () => {
+    const { q } = renderForm();
+
+    expect(q('userKey')).not.toBeNull();
+    expect(q('backupKey')).not.toBeNull();
+    expect(q('bitgoKey')).not.toBeNull();
+    expect(q('walletPassphrase')).not.toBeNull();
+    expect(q('recoveryDestination')).not.toBeNull();
+    expect(q('nestedAtaAddress')).not.toBeNull();
+    expect(q('ownerAtaAddress')).not.toBeNull();
+    expect(q('tokenMintAddress')).not.toBeNull();
+    expect(q('apiKey')).not.toBeNull();
+  });
+
+  it('renders submit button with correct label', () => {
+    renderForm();
+    expect(screen.getByRole('button', { name: /recover tokens/i })).not.toBeNull();
+  });
+
+  it('calls onSubmit with correct values when form is valid', async () => {
+    const onSubmit = vi.fn();
+    const { q } = renderForm(onSubmit);
+
+    fillValidForm(q);
+    fireEvent.click(screen.getByRole('button', { name: /recover tokens/i }));
+
+    await waitFor(() => {
+      expect(onSubmit).toHaveBeenCalledOnce();
+      const [values] = onSubmit.mock.calls[0] as [Record<string, string>][];
+      expect(values.nestedAtaAddress).toBe('FGuZSBhtreqSUsE86xokyjKz2i8VBtJzy6uMXXKyGHug');
+      expect(values.ownerAtaAddress).toBe('Zfm98ZpVafydhFTYcsY6bHgubhB4cFgWFvbdEJxYhTA');
+      expect(values.tokenMintAddress).toBe('ZBCNpuD7YMXzTHB2fhGkGi78MNsHGLRXUhRewNRm9RU');
+      expect(values.recoveryDestination).toBe('7YbcLmVorrH7KCKMj38rFidsruisWi2CmvCTs4cygf8K');
+    });
+  });
+
+  it('does not call onSubmit when required fields are empty', async () => {
+    const onSubmit = vi.fn();
+    renderForm(onSubmit);
+
+    fireEvent.click(screen.getByRole('button', { name: /recover tokens/i }));
+
+    await waitFor(() => {
+      expect(onSubmit).not.toHaveBeenCalled();
+    });
+  });
+
+  it('rejects API key that looks like a URL', async () => {
+    const onSubmit = vi.fn();
+    const { q } = renderForm(onSubmit);
+
+    fillValidForm(q);
+    fireEvent.change(q('apiKey'), {
+      target: { value: 'https://eth-mainnet.g.alchemy.com/v2/somekey' },
+    });
+    fireEvent.click(screen.getByRole('button', { name: /recover tokens/i }));
+
+    await waitFor(() => {
+      expect(onSubmit).not.toHaveBeenCalled();
+      expect(screen.getByText(/api key should not be a url/i)).not.toBeNull();
+    });
+  });
+
+  it('accepts a valid optional API key', async () => {
+    const onSubmit = vi.fn();
+    const { q } = renderForm(onSubmit);
+
+    fillValidForm(q);
+    fireEvent.change(q('apiKey'), {
+      target: { value: 'validApiKey123' },
+    });
+    fireEvent.click(screen.getByRole('button', { name: /recover tokens/i }));
+
+    await waitFor(() => {
+      expect(onSubmit).toHaveBeenCalledOnce();
+    });
+  });
+});