hood-connect

Wallet and onboarding kit for Robinhood Chain dApps (chain 4663 / 46630): one component for add network, fund, connect.

A first-time visitor to a Robinhood Chain dApp almost always has a wallet, almost never has the network added, and has a zero balance on it. Every dApp rebuilds that same three-step onboarding, and every one of them skips the same states: no wallet installed, wallet locked, user rejected the prompt, chain add refused, a prompt already open. hood-connect models the whole thing as one exhaustive state machine and ships the UI for it, in React, in wagmi, and as a framework-free web component.

Docs: https://nirholas.github.io/hood-connect/

Why the chain parameters are the load-bearing part

Adding a network is a single RPC call whose entire contract is one object. Get a field wrong and the wallet rejects it, silently, in every dApp that copied your snippet. MetaMask alone rejects a zero-padded chainId, a currency symbol outside 2 to 6 characters, and a mismatch between the declared chain ID and what the RPC answers to eth_chainId.

hood-connect ships both objects exactly, snapshot-tested against viem's official chain definitions, which is the same source wagmi and the chain's own docs agree on:

import { hoodMainnet, hoodTestnet } from 'hood-connect'

hoodMainnet.addChainParameter
// {
//   chainId: '0x1237',                                        // 4663, unpadded
//   chainName: 'Robinhood Chain',
//   nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
//   rpcUrls: ['https://rpc.mainnet.chain.robinhood.com'],
//   blockExplorerUrls: ['https://robinhoodchain.blockscout.com'],
// }

hoodTestnet.addChainParameter.chainId  // '0xb626' (46630)

tests/chains.test.ts asserts the literal objects, the hex encoding, the symbol length window, the absence of trailing slashes, and agreement with viem. A change to any field fails the build rather than a user's wallet.

The second load-bearing detail is the switch itself. wallet_switchEthereumChain fails with 4902 when the wallet has never heard of the chain, which is the normal case for a first-time visitor, not an error to surface. switchChain() treats 4902 as the signal to add the network and retry, and it also unwraps the -32603 envelope several wallets bury the real code inside.

Install

npm install hood-connect viem

Node >= 20. viem is a peer dependency. react, wagmi, @wagmi/core, and qrcode-generator are optional peers: install only the ones whose entry point you import.

The state machine

Three steps, thirteen states, no unhandled branch.

stateDiagram-v2
    [*] --> idle
    idle --> detecting: start()
    detecting --> no_wallet: nothing announced
    detecting --> disconnected: wallet found
    no_wallet --> detecting: refreshProviders()

    disconnected --> connecting: connect()
    connecting --> locked: no accounts granted
    connecting --> error: 4001 / -32002
    locked --> connecting: retry()

    connecting --> wrong_chain: connected
    wrong_chain --> switching_chain: switchNetwork()
    switching_chain --> adding_chain: 4902
    adding_chain --> switching_chain: added
    switching_chain --> error: rejected
    error --> connecting: retry()

    switching_chain --> checking_balance: on 4663
    checking_balance --> unfunded: no gas
    checking_balance --> ready: funded
    unfunded --> checking_balance: poll / refreshBalances()
    ready --> wrong_chain: chainChanged
    ready --> locked: accountsChanged []
    ready --> disconnected: disconnect()

| Status | Step | What the user sees | |---|---|---| | idle | connect | Nothing yet. The only status rendered on a server. | | detecting | connect | Looking for a wallet. | | no-wallet | connect | Install prompt plus a rescan button. | | disconnected | connect | Connect button, or a picker when several wallets are installed. | | connecting | connect | Waiting on the wallet prompt. | | locked | connect | Unlock instructions plus retry. | | wrong-chain | network | Switch button, with both chain IDs named. | | adding-chain | network | Waiting on the add-network prompt. | | switching-chain | network | Waiting on the switch prompt. | | checking-balance | fund | Reading native and USDG balances. | | unfunded | fund | Bridge routes plus a receive address and QR. | | ready | done | Account summary. The dApp can transact. | | error | (where it failed) | The failure, its recovery hint, and a retry. |

Because the union is exhaustive, a switch over it with no default fails to compile the moment a state goes unhandled.

Quickstart: React

import { HoodConnect } from 'hood-connect/react'

export function Page() {
  return (
    <HoodConnect
      config={{ chain: 'mainnet' }}
      theme="auto"
      onReady={(state) => console.log('ready:', state.address)}
    />
  )
}

Headless, when you want your own markup:

import { useHoodConnect } from 'hood-connect/react'

export function Gate() {
  const hood = useHoodConnect({ chain: 'mainnet' })

  if (hood.status === 'no-wallet') return <a href="https://ethereum.org/en/wallets/find-wallet/">Get a wallet</a>
  if (hood.status === 'wrong-chain') return <button onClick={() => hood.switchNetwork()}>Switch network</button>
  if (hood.status === 'unfunded') return <a href={hood.fundingRoutes[0]?.url}>Bridge in</a>
  if (hood.status === 'ready') return <p>Connected: {hood.address}</p>

  return <button onClick={() => hood.connect()} disabled={hood.pending !== null}>Connect</button>
}

Quickstart: wagmi

The connector wagmi does not ship. Chains, transports, and the add-then-switch behaviour in one import:

import { createHoodConfig } from 'hood-connect/wagmi'

export const config = createHoodConfig({ networks: ['mainnet'], ssr: true })

Or compose it yourself:

import { createConfig } from 'wagmi'
import { hoodConnector, hoodTransports, hoodWagmiChains } from 'hood-connect/wagmi'

export const config = createConfig({
  chains: hoodWagmiChains,
  transports: hoodTransports,
  connectors: [hoodConnector()],
})

Quickstart: plain HTML

<script type="module" src="https://unpkg.com/hood-connect/dist/element/index.js"></script>
<hood-connect chain="mainnet" theme="auto"></hood-connect>

<script type="module">
  document.querySelector('hood-connect').addEventListener('hood-connect:ready', (event) => {
    console.log('ready:', event.detail.address)
  })
</script>

Funding routes

hood-connect does not deploy, hardcode, or call a bridge contract. Robinhood Chain is an Arbitrum Orbit chain, so its canonical deposit path is the Arbitrum bridge portal, and the right thing for a component to do is hand the user a route. The mainnet routes are the ones the chain's own bridging docs list:

| Route | Destination | |---|---| | arbitrum-canonical | https://portal.arbitrum.io/bridge?destinationChain=robinhood-chain&sourceChain=ethereum | | relay | https://relay.link/bridge/robinhood | | across | https://across.to/?to=robinhood | | stargate | https://stargate.finance | | receive | The user's own address, plus an EIP-681 URI and QR |

The receive route is always present and always last, on every network and every configuration, because it is the only route that cannot break. Its URI carries @4663, which is what keeps a scanned code off Ethereum mainnet. The testnet has no documented public bridge, so on testnet receive is the only default route: supply your own with funding.routes rather than expecting one to appear.

createOnboarding({
  funding: {
    extraRoutes: [
      { id: 'ours', label: 'Buy with card', kind: 'bridge', description: 'Our onramp', url: 'https://example.com', official: false },
    ],
  },
})

API

Core (hood-connect)

| Export | What it does | |---|---| | createOnboarding(config) | The state machine. Returns { getState, subscribe, start, connect, addNetwork, switchNetwork, refreshBalances, retry, disconnect, destroy, ... } | | deriveStatus(context, target) | The pure status function the machine uses. Total and testable. | | createProviderStore(options) | EIP-6963 discovery. SSR-safe, reference-stable snapshots. | | hoodMainnet / hoodTestnet | Chain metadata plus the exact addChainParameter. | | resolveHoodChain(4663 \| 'mainnet') | Chain lookup by ID or alias. | | Wallet primitives | requestAccounts, getAccounts, getChainId, addChain, switchChain, watchAccounts, watchChain, watchDisconnect, revokePermissions | | readBalances(source, chain, address) | Native and USDG balances over a provider or an HTTP RPC. | | buildFundingRoutes(chain, address, options) | The funding routes for a chain and account. | | buildView(state, options) | The pure state-to-UI projection both renderers use. | | HoodConnectError | Normalised failure with .code, .hint, .retryable, .providerCode. |

OnboardingConfig: chain, rpcUrl, requireFunding, minNativeWei, autoConnect, autoSwitchChain, funding, storage, storageKey, balanceRefreshIntervalMs, includeLegacyWindowEthereum, detectionTimeoutMs.

Every action resolves with the new state and never rejects on a wallet-level failure, so a click handler cannot produce an unhandled rejection. Failures land in state.error.

React (hood-connect/react)

| Export | Signature | |---|---| | <HoodConnect /> | See the prop table below | | <HoodConnectProvider config> | Shares one machine across a tree | | useHoodConnect(config?) | Full state plus bound connect / switchNetwork / addNetwork / refreshBalances / retry / disconnect / refreshProviders / clearError | | useProviders(config?) | The discovered wallets | | useOnboardingStatus(config?) | Just the status |

| Prop | Type | Default | Notes | |---|---|---|---| | config | OnboardingConfig | {} | Read once, on first render | | theme | 'auto' \| 'light' \| 'dark' | 'auto' | auto follows prefers-color-scheme | | unstyled | boolean | false | Drops the stylesheet, keeps the markup and ARIA | | className | string | | Added to the root | | labels | ViewLabels | | Overrides for every string rendered | | installUrl | string | ethereum.org wallet finder | Where a user with no wallet is sent | | showDisconnect | boolean | true | | | showQrCode | boolean | true | Needs the optional qrcode-generator peer | | onStatusChange | (status, state) => void | | Every transition | | onReady | (state) => void | | Once per arrival at ready | | onError | (error, state) => void | | Every new error |

wagmi (hood-connect/wagmi)

hoodConnector(params), createHoodConfig(params), hoodWagmiChains, hoodTransports, robinhoodChain, robinhoodChainTestnet.

Web component (hood-connect/element)

Attributes: chain, theme, rpc-url, auto-connect, auto-switch-chain, require-funding, min-native-wei, install-url, show-qr, show-disconnect, unstyled.

Events (all bubble and cross the shadow boundary): hood-connect:status, hood-connect:ready, hood-connect:account, hood-connect:error. The machine is on the element as .onboarding, the snapshot as .state.

Theming

Every colour is a CSS custom property on .hc-root. Override the ones you care about:

.hc-root {
  --hc-accent: #6d5efc;
  --hc-radius: 8px;
  --hc-font: 'Inter', sans-serif;
}

Full list: --hc-bg, --hc-bg-inset, --hc-border, --hc-border-strong, --hc-text, --hc-text-dim, --hc-text-faint, --hc-accent, --hc-accent-text, --hc-accent-soft, --hc-danger, --hc-danger-soft, --hc-focus, --hc-shadow, --hc-radius, --hc-radius-sm, --hc-gap, --hc-font, --hc-mono.

For total control, unstyled keeps the markup, the hc- classes, and the ARIA wiring and drops only the stylesheet.

Examples

npm install
npm run build

npm run example:react   # Vite + React, both the component and the headless hook
npm run example:html    # the web component on a plain page, no bundler

See INTEGRATION.md for wiring into Next.js, Vite, wagmi, and a plain page.

Limits and caveats

• Balances read through the connected wallet by default. That is correct by construction once the wallet is on the target chain and it needs no CORS allowance, but it means no balance is read while the wallet is elsewhere. Pass rpcUrl to read over HTTP instead.
• wallet_revokePermissions is a MetaMask extension, not a standard. disconnect({ revoke: true }) resolves either way; on a wallet without it the session is only dropped locally.
• A wallet with no wallet_addEthereumChain cannot be onboarded from a website. The flow reports unsupported-method, marks it non-retryable, and tells the user to switch manually. Some mobile in-app browsers behave this way.
• The QR code needs the optional qrcode-generator peer. Without it the funding step still renders the address, the copy button, the explorer link, and the EIP-681 URI. On a page with no bundler, one UMD script tag is enough: the loader checks the global first.
• No bridge contract is called. Funding routes are links. Nothing in this package moves funds, signs a transaction, or holds a key.
• Testnet has no documented public bridge. receive is the only default route there.
• config is read once per machine. To retarget a different network, remount the component (see examples/react/src/App.tsx) or create a new machine.

Related

Part of the Robinhood Chain fleet: hoodchain (SDK), hoodkit (streams, indexer, hooks), hood402 (x402 payments over USDG).

License

Proprietary, all rights reserved. See LICENSE.