@tuwaio/orbit-core 0.3.0 → 0.3.1

package/README.md

@@ -1,18 +1,21 @@
 # @tuwaio/orbit-core
 
 [![NPM Version](https://img.shields.io/npm/v/@tuwaio/orbit-core.svg)](https://www.npmjs.com/package/@tuwaio/orbit-core)
-[![License](https://img.shields.io/npm/l/@tuwaio/orbit-core.svg)](./LICENSE)
+[![License](https://img.shields.io/npm/l/@tuwaio/orbit-core.svg)](https://github.com/TuwaIO/orbit/blob/main/packages/orbit-core/LICENSE)
 
-`@tuwaio/orbit-core` is the Layer 1 (L1) core logic and foundational state wrapper layer of the TUWA Orbit multi-chain framework. It is completely **headless** and **framework-agnostic**, engineered to decouple raw blockchain connection interfaces from visual frontend layers. By establishing a unified type-safe interface, it enables consistent cross-chain connection management and persistent user account tracking.
+`@tuwaio/orbit-core` is the Layer 1 (L1) package of **Orbit Utils**, the Stage 1 primitives layer of the TUWA ecosystem. It defines the chain-agnostic types that the Orbit chain packages and the higher TUWA layers (Satellite Connect, Pulsar) share, and ships small helpers for connector naming, address validation, error normalization and SSR-safe connection persistence.
+
+The package has **zero runtime dependencies** and imports no Web3 SDK, so it runs in any framework, in the browser and on the server.
 
 ---
 
 ## 🏛️ Core Capabilities
 
-- **Unified Multi-Chain Primitives:** Establishes the structural `BaseAdapter` interface and the `OrbitAdapter` enum (EVM, Solana, Starknet) to serve as the abstract layer for multi-chain communication.
-- **Connection State Persistence:** Implements SSR-safe storage helpers (`lastConnectedConnectorHelpers`, `recentConnectedConnectorHelpers`) to track and resume wallet connection history via `localStorage`.
-- **Autonomy-Focused Utilities:** Technical utility helpers for formatting chain IDs, parsing connector names, and executing asynchronous operations (`waitFor`, `delay`).
-- **Account Impersonation Engine:** Built-in `impersonatedHelpers` for sandboxed testing and account auditing.
+- **Multi-chain primitives:** the `OrbitAdapter` enum (`evm`, `solana`, `starknet`), the `BaseAdapter` contract, `ConnectorType` identifiers such as `"evm:metamask"` or `"solana:phantom"`, and `selectAdapterByKey` to pick the adapter of the active chain.
+- **Connector helpers:** `getConnectorTypeFromName`, `getAdapterFromConnectorType`, `formatConnectorName`, `formatConnectorChainId`, `isSolanaChain`, `setChainId` and `getNetworkData`.
+- **Validation and errors:** `isAddress` validates EVM (hex) and Solana (Base58) addresses. `normalizeError` turns any wallet, viem or RPC error into a JSON-serializable `TuwaErrorState` that is safe to persist.
+- **Connection persistence:** `lastConnectedConnectorHelpers` and `recentlyConnectedConnectorsListHelpers` keep connection history in `localStorage` and do nothing during SSR.
+- **Runtime utilities:** `detectSafeApp` (Safe{Wallet} iframe detection), `waitFor`, `delay`, `filterUniqueByKey`, and `impersonatedHelpers` for development and testing.
 
 ---
 
@@ -24,71 +27,87 @@ pnpm add @tuwaio/orbit-core
 
 ---
 
-## 🚀 Architectural Integration
+## 🚀 Usage
 
-### Runtime Adapter Resolution
+### Resolving the active adapter
 
-Register and resolve chain-specific primitive adapters dynamically:
+`BaseAdapter` describes what an adapter can do; add a `key` to register it for a chain family:
 
 ```typescript
-import { OrbitAdapter, selectAdapterByKey, BaseAdapter } from '@tuwaio/orbit-core';
-
-// Configure primitive adapter mapping
-const adapters: BaseAdapter[] = [
-  {
-    key: OrbitAdapter.EVM,
-    getExplorerUrl: (url) => `https://etherscan.io/${url}`,
-  },
-  {
-    key: OrbitAdapter.SOLANA,
-    getExplorerUrl: (url, cluster) => `https://solscan.io/${url}?cluster=${cluster}`,
-  },
-];
+import { type BaseAdapter, OrbitAdapter, selectAdapterByKey } from '@tuwaio/orbit-core';
 
-// Dynamically select target execution adapter
-const activeAdapter = selectAdapterByKey({
-  adapterKey: OrbitAdapter.SOLANA,
-  adapter: adapters,
-});
+type ExplorerAdapter = BaseAdapter & { key: OrbitAdapter };
 
-if (activeAdapter) {
-  console.log(activeAdapter.getExplorerUrl('tx/0x...', 'mainnet-beta'));
-}
+const adapters: ExplorerAdapter[] = [
+  { key: OrbitAdapter.EVM, getExplorerUrl: (path) => `https://etherscan.io/${path ?? ''}` },
+  { key: OrbitAdapter.SOLANA, getExplorerUrl: (path) => `https://explorer.solana.com/${path ?? ''}` },
+];
+
+const solanaAdapter = selectAdapterByKey({ adapterKey: OrbitAdapter.SOLANA, adapter: adapters });
+solanaAdapter?.getExplorerUrl('tx/<signature>'); // "https://explorer.solana.com/tx/<signature>"
 ```
 
-### Connection State Storage
+If no adapter matches the key, `selectAdapterByKey` falls back to the first adapter in the array and logs a warning.
 
-Read and write connected connector metadata securely with `localStorage` fallback checks:
+### Persisting the last connection
 
 ```typescript
 import { lastConnectedConnectorHelpers } from '@tuwaio/orbit-core';
 
-// Persist metadata
 lastConnectedConnectorHelpers.setLastConnectedConnector({
   connectorType: 'evm:metamask',
   chainId: 1,
-  address: '0x123...',
+  address: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045',
 });
 
-// Retrieve connection metadata safely during client-side hydration
+// Returns undefined on the server and when nothing is stored.
 const lastConnected = lastConnectedConnectorHelpers.getLastConnectedConnector();
-console.log(lastConnected?.address); // "0x123..."
 ```
 
+### Normalizing errors
+
+```typescript
+import { normalizeError } from '@tuwaio/orbit-core';
+
+declare function sendTransaction(): Promise<void>;
+
+try {
+  await sendTransaction();
+} catch (error) {
+  // `message` prefers viem's `shortMessage`; `raw` is a JSON-safe copy of the error details.
+  const { message, raw } = normalizeError(error);
+}
+```
+
+### Validating addresses
+
+```typescript
+import { isAddress } from '@tuwaio/orbit-core';
+
+isAddress('0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'); // true (auto-detected as EVM)
+isAddress('So11111111111111111111111111111111111111112', 'solana'); // true
+```
+
+`isAddress` checks the address format only (hex length or Base58 alphabet); it does not verify EVM checksums.
+
 ---
 
-## 🔧 API & Module Architecture
+## 🗄️ Browser Storage
 
-`@tuwaio/orbit-core` exposes the following modules:
+The storage helpers write the following `localStorage` keys. Clear them to reset the connection state of a user:
 
-- **Core Primitives:** `OrbitAdapter`, `BaseAdapter`, `ConnectorType`, `RecentlyConnectedConnectorData`.
-- **Registry Resolvers:** `selectAdapterByKey`, `getAdapterFromConnectorType`, `getConnectorTypeFromName`.
-- **Formatters:** `formatConnectorName`, `formatConnectorChainId`.
-- **Storage Helpers:** `lastConnectedConnectorHelpers`, `recentConnectedConnectorHelpers`, `impersonatedHelpers`.
-- **Core Primitives:** `isSafeApp`, `delay`, `waitFor`, `filterUniqueByKey`.
+| Key                                                 | Written by                               |
+| --------------------------------------------------- | ---------------------------------------- |
+| `orbit-core:lastConnectedConnector`                 | `lastConnectedConnectorHelpers`          |
+| `orbit-core:recentlyConnectedConnectorsListHelpers` | `recentlyConnectedConnectorsListHelpers` |
+| `satellite-connect:impersonatedAddress`             | `impersonatedHelpers`                    |
 
 ---
 
+## 📚 API Reference
+
+Every export, with signatures and types generated from the source, is documented at **[orbit.docs.tuwa.io/packages/orbit-core](https://orbit.docs.tuwa.io/packages/orbit-core)**.
+
 ## 📄 License
 
-Licensed under the **Apache-2.0 License**. See the [LICENSE](./LICENSE) file for details.
+Licensed under the **Apache-2.0 License**. See the [LICENSE](https://github.com/TuwaIO/orbit/blob/main/packages/orbit-core/LICENSE) file for details.

package/dist/index.d.mts

@@ -48,8 +48,10 @@ declare enum OrbitAdapter {
      * For the Starknet L2 network.
      * Supports:
      * - Starknet Mainnet
-     * - Testnet (Goerli)
+     * - Starknet Sepolia testnet
      * - Other Starknet deployments
+     *
+     * Reserved for future use: no Orbit chain package implements Starknet yet.
      */
     Starknet = "starknet"
 }
@@ -90,6 +92,10 @@ type OrbitGenericAdapter<A extends {
 }> = {
     adapter: A | A[];
 };
+/**
+ * Minimal contract shared by chain adapters: explorer links plus optional name-service lookups.
+ * Combine it with a `key: OrbitAdapter` property to register an adapter for {@link selectAdapterByKey}.
+ */
 type BaseAdapter = {
     /**
      * Generates blockchain explorer URL
@@ -144,8 +150,6 @@ declare function isSolanaChain(chainId: number | string): boolean;
 declare function setChainId(chainId: number | string): string | number;
 
 /**
- * @name delay
- *
  * Ensures the global 'window' object is available (if running in a browser-like environment),
  * then pauses execution for a specified duration, and finally resolves the Promise with the given value.
  *
@@ -188,8 +192,36 @@ declare const delay: <T>(value: T, ms: number) => Promise<T>;
  */
 declare function filterUniqueByKey<T>(array: T[], key: keyof T): T[];
 
+/**
+ * Formats a chain ID for use in connector identifiers.
+ * String chain IDs (e.g. Solana cluster names) are prefixed with the adapter key; numeric EVM chain IDs are kept as is.
+ *
+ * @example
+ * ```typescript
+ * formatConnectorChainId('devnet', OrbitAdapter.SOLANA); // "solana:devnet"
+ * formatConnectorChainId(1, OrbitAdapter.EVM); // 1
+ * ```
+ *
+ * @param chainId - Numeric EVM chain ID or string chain identifier.
+ * @param connectedAdapter - Adapter of the connected wallet.
+ * @returns `"<adapter>:<chainId>"` for string chain IDs, otherwise the numeric chain ID unchanged.
+ */
 declare function formatConnectorChainId(chainId: string | number, connectedAdapter: OrbitAdapter): string | number;
 
+/**
+ * Normalizes a wallet connector display name into a stable identifier.
+ * Known names are mapped explicitly (e.g. "Trust Wallet" → "trust", "Base Account" → "coinbase");
+ * any other name has its whitespace removed and is lowercased.
+ *
+ * @example
+ * ```typescript
+ * formatConnectorName('Trust Wallet'); // "trust"
+ * formatConnectorName('Rabby Wallet'); // "rabbywallet"
+ * ```
+ *
+ * @param connectorName - Display name reported by the wallet connector.
+ * @returns The normalized connector identifier.
+ */
 declare const formatConnectorName: (connectorName: string) => string;
 
 /**
@@ -245,6 +277,14 @@ declare function getAdapterFromConnectorType(connectorType: ConnectorType): Orbi
  */
 declare function getConnectorTypeFromName(adapter: OrbitAdapter, name: string): string;
 
+/**
+ * Returns the default network and educational links for an adapter, e.g. to render a
+ * "What is a wallet?" section in a connect modal.
+ *
+ * @param adapter - The adapter to describe.
+ * @returns Default chain (`chainId`, `name`) and `links` (`aboutNetwork`, `choseWallet`, `about`) for EVM and Solana,
+ * or `undefined` for adapters without network data (e.g. Starknet).
+ */
 declare const getNetworkData: (adapter: OrbitAdapter) => {
     chain: {
         chainId: number;
@@ -317,14 +357,22 @@ declare const impersonatedHelpers: {
      * @returns The impersonated address or undefined if not set or in SSR context
      */
     getImpersonated: () => string | null | undefined;
+    /**
+     * Removes the impersonated address from localStorage.
+     *
+     * @returns undefined in SSR context, void in browser
+     */
     removeImpersonated: () => void;
 };
 
 /**
  * Checks if the current window is running inside a Safe App iframe
  * by attempting postMessage communication with the parent window.
+ * Side effect: posts a `getSafeInfo` message to `window.parent` and listens for the reply until `timeout`.
  *
- * @returns Promise that resolves to true if running inside Safe Wallet, false otherwise
+ * @param timeout - How long to wait for the Safe response, in milliseconds. Defaults to 1000.
+ * @returns Promise that resolves to true if running inside Safe Wallet, false otherwise (also on the server,
+ * outside an iframe, or when not served over HTTPS)
  */
 declare function detectSafeApp(timeout?: number): Promise<boolean>;
 /**
@@ -338,9 +386,15 @@ declare const isInSecureIframe: boolean;
  */
 declare const isSafeApp: boolean;
 
+/**
+ * Connection data persisted by {@link lastConnectedConnectorHelpers}.
+ */
 type LastConnectedConnector = {
+    /** Connector identifier, e.g. "evm:metamask". */
     connectorType: ConnectorType;
+    /** Chain the wallet was connected to (numeric EVM chain ID or Solana chain identifier). */
     chainId: number | string;
+    /** Connected wallet address, if known. */
     address?: string;
 };
 /**
@@ -360,7 +414,7 @@ declare const lastConnectedConnectorHelpers: {
     /**
      * Stores the last connected wallet data in localStorage.
      *
-     * @param data - Object containing the wallet type and chain ID.
+     * @param data - Connector type, chain ID and optional address of the connected wallet.
      * @returns undefined in SSR context, void in browser
      */
     setLastConnectedConnector: ({ connectorType, chainId, address }: LastConnectedConnector) => void;
@@ -692,6 +746,21 @@ declare const selectAdapterByKey: <A extends {
     adapterKey: OrbitAdapter;
 } & OrbitGenericAdapter<A>) => A | undefined;
 
+/**
+ * Polls a predicate until it returns a truthy value.
+ *
+ * @example
+ * ```typescript
+ * // Wait up to 10 seconds (50 × 200 ms) for an injected provider.
+ * await waitFor(() => typeof window !== 'undefined' && 'ethereum' in window);
+ * ```
+ *
+ * @param predicate - Condition to check on every attempt.
+ * @param maxChecks - Maximum number of attempts. Defaults to 50.
+ * @param checkIntervalMs - Delay between attempts in milliseconds. Defaults to 200.
+ * @returns A promise that resolves as soon as the predicate is truthy.
+ * @throws {Error} "Predicate not fulfilled in time" if the predicate is still falsy after `maxChecks` attempts.
+ */
 declare function waitFor(predicate: () => boolean | undefined, maxChecks?: number, checkIntervalMs?: number): Promise<void>;
 
-export { type BaseAdapter, type ChainIdentifierArray, type ConnectorType, OrbitAdapter, type OrbitGenericAdapter, type RecentlyConnectedConnectorData, type RecentlyConnectedConnectorsList, type TuwaErrorState, delay, detectSafeApp, filterUniqueByKey, formatConnectorChainId, formatConnectorName, getAdapterFromConnectorType, getConnectorTypeFromName, getNetworkData, getParsedStorageItem, impersonatedHelpers, isAddress, isInSecureIframe, isSafeApp, isSolanaChain, lastConnectedConnectorHelpers, normalizeError, recentlyConnectedConnectorsListHelpers, selectAdapterByKey, setChainId, waitFor };
+export { type BaseAdapter, type ChainIdentifierArray, type ConnectorType, type LastConnectedConnector, OrbitAdapter, type OrbitGenericAdapter, type RecentlyConnectedConnectorData, type RecentlyConnectedConnectorsList, type TuwaErrorState, delay, detectSafeApp, filterUniqueByKey, formatConnectorChainId, formatConnectorName, getAdapterFromConnectorType, getConnectorTypeFromName, getNetworkData, getParsedStorageItem, impersonatedHelpers, isAddress, isInSecureIframe, isSafeApp, isSolanaChain, lastConnectedConnectorHelpers, normalizeError, recentlyConnectedConnectorsListHelpers, selectAdapterByKey, setChainId, waitFor };

package/dist/index.d.ts

@@ -48,8 +48,10 @@ declare enum OrbitAdapter {
      * For the Starknet L2 network.
      * Supports:
      * - Starknet Mainnet
-     * - Testnet (Goerli)
+     * - Starknet Sepolia testnet
      * - Other Starknet deployments
+     *
+     * Reserved for future use: no Orbit chain package implements Starknet yet.
      */
     Starknet = "starknet"
 }
@@ -90,6 +92,10 @@ type OrbitGenericAdapter<A extends {
 }> = {
     adapter: A | A[];
 };
+/**
+ * Minimal contract shared by chain adapters: explorer links plus optional name-service lookups.
+ * Combine it with a `key: OrbitAdapter` property to register an adapter for {@link selectAdapterByKey}.
+ */
 type BaseAdapter = {
     /**
      * Generates blockchain explorer URL
@@ -144,8 +150,6 @@ declare function isSolanaChain(chainId: number | string): boolean;
 declare function setChainId(chainId: number | string): string | number;
 
 /**
- * @name delay
- *
  * Ensures the global 'window' object is available (if running in a browser-like environment),
  * then pauses execution for a specified duration, and finally resolves the Promise with the given value.
  *
@@ -188,8 +192,36 @@ declare const delay: <T>(value: T, ms: number) => Promise<T>;
  */
 declare function filterUniqueByKey<T>(array: T[], key: keyof T): T[];
 
+/**
+ * Formats a chain ID for use in connector identifiers.
+ * String chain IDs (e.g. Solana cluster names) are prefixed with the adapter key; numeric EVM chain IDs are kept as is.
+ *
+ * @example
+ * ```typescript
+ * formatConnectorChainId('devnet', OrbitAdapter.SOLANA); // "solana:devnet"
+ * formatConnectorChainId(1, OrbitAdapter.EVM); // 1
+ * ```
+ *
+ * @param chainId - Numeric EVM chain ID or string chain identifier.
+ * @param connectedAdapter - Adapter of the connected wallet.
+ * @returns `"<adapter>:<chainId>"` for string chain IDs, otherwise the numeric chain ID unchanged.
+ */
 declare function formatConnectorChainId(chainId: string | number, connectedAdapter: OrbitAdapter): string | number;
 
+/**
+ * Normalizes a wallet connector display name into a stable identifier.
+ * Known names are mapped explicitly (e.g. "Trust Wallet" → "trust", "Base Account" → "coinbase");
+ * any other name has its whitespace removed and is lowercased.
+ *
+ * @example
+ * ```typescript
+ * formatConnectorName('Trust Wallet'); // "trust"
+ * formatConnectorName('Rabby Wallet'); // "rabbywallet"
+ * ```
+ *
+ * @param connectorName - Display name reported by the wallet connector.
+ * @returns The normalized connector identifier.
+ */
 declare const formatConnectorName: (connectorName: string) => string;
 
 /**
@@ -245,6 +277,14 @@ declare function getAdapterFromConnectorType(connectorType: ConnectorType): Orbi
  */
 declare function getConnectorTypeFromName(adapter: OrbitAdapter, name: string): string;
 
+/**
+ * Returns the default network and educational links for an adapter, e.g. to render a
+ * "What is a wallet?" section in a connect modal.
+ *
+ * @param adapter - The adapter to describe.
+ * @returns Default chain (`chainId`, `name`) and `links` (`aboutNetwork`, `choseWallet`, `about`) for EVM and Solana,
+ * or `undefined` for adapters without network data (e.g. Starknet).
+ */
 declare const getNetworkData: (adapter: OrbitAdapter) => {
     chain: {
         chainId: number;
@@ -317,14 +357,22 @@ declare const impersonatedHelpers: {
      * @returns The impersonated address or undefined if not set or in SSR context
      */
     getImpersonated: () => string | null | undefined;
+    /**
+     * Removes the impersonated address from localStorage.
+     *
+     * @returns undefined in SSR context, void in browser
+     */
     removeImpersonated: () => void;
 };
 
 /**
  * Checks if the current window is running inside a Safe App iframe
  * by attempting postMessage communication with the parent window.
+ * Side effect: posts a `getSafeInfo` message to `window.parent` and listens for the reply until `timeout`.
  *
- * @returns Promise that resolves to true if running inside Safe Wallet, false otherwise
+ * @param timeout - How long to wait for the Safe response, in milliseconds. Defaults to 1000.
+ * @returns Promise that resolves to true if running inside Safe Wallet, false otherwise (also on the server,
+ * outside an iframe, or when not served over HTTPS)
  */
 declare function detectSafeApp(timeout?: number): Promise<boolean>;
 /**
@@ -338,9 +386,15 @@ declare const isInSecureIframe: boolean;
  */
 declare const isSafeApp: boolean;
 
+/**
+ * Connection data persisted by {@link lastConnectedConnectorHelpers}.
+ */
 type LastConnectedConnector = {
+    /** Connector identifier, e.g. "evm:metamask". */
     connectorType: ConnectorType;
+    /** Chain the wallet was connected to (numeric EVM chain ID or Solana chain identifier). */
     chainId: number | string;
+    /** Connected wallet address, if known. */
     address?: string;
 };
 /**
@@ -360,7 +414,7 @@ declare const lastConnectedConnectorHelpers: {
     /**
      * Stores the last connected wallet data in localStorage.
      *
-     * @param data - Object containing the wallet type and chain ID.
+     * @param data - Connector type, chain ID and optional address of the connected wallet.
      * @returns undefined in SSR context, void in browser
      */
     setLastConnectedConnector: ({ connectorType, chainId, address }: LastConnectedConnector) => void;
@@ -692,6 +746,21 @@ declare const selectAdapterByKey: <A extends {
     adapterKey: OrbitAdapter;
 } & OrbitGenericAdapter<A>) => A | undefined;
 
+/**
+ * Polls a predicate until it returns a truthy value.
+ *
+ * @example
+ * ```typescript
+ * // Wait up to 10 seconds (50 × 200 ms) for an injected provider.
+ * await waitFor(() => typeof window !== 'undefined' && 'ethereum' in window);
+ * ```
+ *
+ * @param predicate - Condition to check on every attempt.
+ * @param maxChecks - Maximum number of attempts. Defaults to 50.
+ * @param checkIntervalMs - Delay between attempts in milliseconds. Defaults to 200.
+ * @returns A promise that resolves as soon as the predicate is truthy.
+ * @throws {Error} "Predicate not fulfilled in time" if the predicate is still falsy after `maxChecks` attempts.
+ */
 declare function waitFor(predicate: () => boolean | undefined, maxChecks?: number, checkIntervalMs?: number): Promise<void>;
 
-export { type BaseAdapter, type ChainIdentifierArray, type ConnectorType, OrbitAdapter, type OrbitGenericAdapter, type RecentlyConnectedConnectorData, type RecentlyConnectedConnectorsList, type TuwaErrorState, delay, detectSafeApp, filterUniqueByKey, formatConnectorChainId, formatConnectorName, getAdapterFromConnectorType, getConnectorTypeFromName, getNetworkData, getParsedStorageItem, impersonatedHelpers, isAddress, isInSecureIframe, isSafeApp, isSolanaChain, lastConnectedConnectorHelpers, normalizeError, recentlyConnectedConnectorsListHelpers, selectAdapterByKey, setChainId, waitFor };
+export { type BaseAdapter, type ChainIdentifierArray, type ConnectorType, type LastConnectedConnector, OrbitAdapter, type OrbitGenericAdapter, type RecentlyConnectedConnectorData, type RecentlyConnectedConnectorsList, type TuwaErrorState, delay, detectSafeApp, filterUniqueByKey, formatConnectorChainId, formatConnectorName, getAdapterFromConnectorType, getConnectorTypeFromName, getNetworkData, getParsedStorageItem, impersonatedHelpers, isAddress, isInSecureIframe, isSafeApp, isSolanaChain, lastConnectedConnectorHelpers, normalizeError, recentlyConnectedConnectorsListHelpers, selectAdapterByKey, setChainId, waitFor };

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@tuwaio/orbit-core",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "private": false,
   "author": "Oleksandr Tkach",
   "license": "Apache-2.0",
-  "description": "Layer 1 (L1) of the TUWA Ecosystem. Framework-agnostic library for abstracting core multi-chain types, errors, and localStorage helper utilities.",
+  "description": "L1 core of Orbit Utils (TUWA): zero-dependency, framework-agnostic multi-chain types, connector and address helpers, error normalization and SSR-safe connection persistence.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
@@ -16,9 +16,14 @@
     "socket.json"
   ],
   "keywords": [
+    "tuwa",
+    "orbit",
     "web3",
+    "multi-chain",
+    "evm",
+    "solana",
     "typescript",
-    "core",
+    "framework-agnostic",
     "headless"
   ],
   "repository": {
@@ -38,7 +43,7 @@
   ],
   "devDependencies": {
     "tsup": "^8.5.1",
-    "typescript": "^6.0.3"
+    "typescript": "6.0.3"
   },
   "scripts": {
     "start": "tsup src/index.ts --watch",