# OpenSpec Change: enterprise-react-crypto

- **Change ID**: enterprise-react-crypto
- **Package**: `@suaveplan/react-crypto`
- **Category**: react
- **Target path**: `react/auth/react-crypto`
- **Status**: PROPOSED
- **Date**: 2026-04-24
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/react-crypto.md`

---

## Summary

Deliver `@suaveplan/react-crypto` on genesis from scratch at enterprise quality. Wallet UI for EVM chains: `WalletConnect`, `AddressDisplay`, `BalanceDisplay`, `TransactionList`, and `useWallet` hook — fully implemented (no stub `0x000...` address, no README-vs-reality gaps). Integrates with `@suaveplan/crypto` for signing and `@suaveplan/crypto-browser` for WebCrypto operations. `useWallet` fully implements MetaMask/WalletConnect via injected provider interface, `autoConnect`, `switchNetwork`, `sendTransaction`, `signMessage`.

---

## Current-state audit (genesis)

Package does not exist on genesis — fresh build.

---

## Available workspace deps on genesis

| Package | Role |
|---|---|
| `@suaveplan/error` (`workspace:^`) | `WalletError` |
| `@suaveplan/crypto` (`workspace:^`) | Signing utilities |
| `@suaveplan/crypto-browser` (`workspace:^`) | WebCrypto adapters |
| `@suaveplan/react-translate` (`workspace:^`) | i18n |
| `zod` (`catalog:forms`) | Network/transaction schemas |
| `@opentelemetry/api` (`catalog:observability`) | `wallet.connect` / `wallet.sign` spans |

External: `tslib catalog:build`. React 18 peer.

---

## Public API surface

```ts
WalletConnect, AddressDisplay, BalanceDisplay, TransactionList
useWallet

explorerUrl, formatAddress, formatBalance, isValidEvmAddress, networkDisplayName

// Types
Network, TokenBalance, Transaction, TransactionDirection, TransactionStatus,
WalletInfo, WalletStatus
```

---

## New additions for genesis

1. **Full `useWallet` implementation** — injected `WalletProvider` interface (MetaMask/WalletConnect adapters); `connect()`, `disconnect()`, `autoConnect`, `switchNetwork(chainId)`, `sendTransaction(tx)`, `signMessage(msg)`. No stubs.
2. **`WalletError`** — codes: `WALLET_CONNECT_FAILED`, `WALLET_NOT_CONNECTED`, `WALLET_SIGN_FAILED`, `WALLET_NETWORK_ERROR`.
3. **OTel spans** — `wallet.connect`, `wallet.sign`, `wallet.send_transaction`.
4. **Stories** — connected, disconnected, loading, wrong-network, playground.
5. **Playwright E2E** — injected mock provider; connect → address shown; signMessage → tx hash shown.

---

## File layout

```text
react/auth/react-crypto/
  package.json
  tsconfig.json
  vitest.config.ts
  src/
    index.ts
    hooks/
      use-wallet/ (ts + types + md + test + stories + index)
    components/
      wallet-connect/ address-display/ balance-display/ transaction-list/
    providers/
      wallet-provider/ (ts + types + md + test + index)
    utils/
      evm-utils/ (ts + md + test + index)
    types/
      crypto.types.ts
  e2e/
    wallet.spec.ts
```