@nexus-cross/connect-kit-core

Pure domain layer for crossx-kit — TypeScript types, port interfaces, and framework-agnostic utilities. This package has no runtime dependencies on wagmi, viem, React, or any wallet SDK. It is the seam that lets the wagmi and React layers evolve independently.

DApp developers normally don't install this package directly. Install @nexus-cross/connect-kit-react (and optionally @nexus-cross/connect-kit-wagmi) — both re-export the types you need.

Install

pnpm add @nexus-cross/connect-kit-core

What's inside

Domain types

import type {
  // Wallet taxonomy
  WalletId,            // 'cross_embedded' | 'cross_wallet' | 'cross_extension' | 'metamask' | 'binance' | (string & {})
  ConnectorType,       // 'embedded' | 'app' | 'extension' | 'external'
  WalletDescriptor,

  // Connection result
  Account,
  ConnectorResult,
  ChainBalance,

  // Kit config (input to createCrossxConfig)
  CrossConnectKitConfig,
  AppMetadata,
  NetworkConfig,

  // UI / Theme
  ModalView,
  Theme,
  ThemeMode,           // 'light' | 'dark'
  ThemeTokens,

  // PIN keyboard (embedded SDK modal behavior)
  PinKeyboardMode,     // 'virtual' | 'native'
  PinKeyboardOption,   // PinKeyboardMode | (() => PinKeyboardMode)

  // Misc
  Unsubscribe,
  WalletState,
} from '@nexus-cross/connect-kit-core';

import { ConnectionStatus } from '@nexus-cross/connect-kit-core';
// ConnectionStatus.CONNECTED | .DISCONNECTED | .CONNECTING | .RECONNECTING

Ports (capability interfaces)

Ports describe what the kit needs from its environment, not how it is delivered. Adapters in @nexus-cross/connect-kit-wagmi and @nexus-cross/connect-kit-react implement them.

import type {
  ConnectorPort,        // Connect / disconnect / subscribe to wallet state
  StoragePort,          // Async key-value storage (localStorage, cookies, …)
  ModalControlPort,     // Open / close the kit's modal views
  ThemePort,            // Read & write theme tokens
  WalletDetectionPort,  // EIP-6963 / injected / SDK wallet discovery
  BalancePort,          // Per-chain balance fetcher
} from '@nexus-cross/connect-kit-core';

Ports are the only contract core has with the outside world — any new external capability must enter through a port, never as a direct dependency.

Utilities

BigInt-safe formatters for blockchain numerics. These always floor when truncating decimals and never round up or use banker's rounding.

import { formatBalance, formatWei } from '@nexus-cross/connect-kit-core';

formatBalance(1234567890000000000n, 18);      // '1.234567890000000000'
formatBalance(1234567890000000000n, 18, 4);   // '1.2345'  (truncated)
formatWei('0xde0b6b3a7640000');               // '1'       (1 ETH)

Design rules

The core package enforces the architectural spine:

• No environment dependencies — no wagmi, viem, React, DOM, or Node APIs. Anything impure lives behind a port.
• Constructor injection only — no singletons, no module-level globals, no hidden window access.
• BigInt end-to-end — wei / gas / balance values stay in BigInt through every computation; display values are UI-only and never fed back into arithmetic.
• External SDK types don't leak — the wagmi package converts between external shapes (viem Address, wagmi Connector) and core's plain types (string addresses, WalletDescriptor) at its own boundary.

Compatibility

• TypeScript 5.x
• Node 18+ / modern browsers (ES2020 target)
• No peer dependencies

License

MIT