@rango-dev/wallets-core 0.0.0-experimental-936229e8-20251208

package/src/legacy/helpers.ts

@@ -0,0 +1,75 @@
+import type { Network } from './types.js';
+import type { Options } from './wallet.js';
+import type { BlockchainMeta } from 'rango-types';
+
+import { Networks } from './types.js';
+
+export function formatAddressWithNetwork(
+  address: string,
+  network?: Network | null
+) {
+  return `${network || ''}:${address}`;
+}
+
+export function accountAddressesWithNetwork(
+  addresses: string[] | null,
+  network?: Network | null
+) {
+  if (!addresses) {
+    return [];
+  }
+
+  return addresses.map((address) => {
+    return formatAddressWithNetwork(address, network);
+  });
+}
+
+export function readAccountAddress(addressWithNetwork: string): {
+  address: string;
+  network: Network;
+} {
+  const [network, address] = addressWithNetwork.split(':');
+
+  return {
+    network,
+    address,
+  };
+}
+
+export function needsCheckInstallation(options: Options) {
+  const { checkInstallation = true } = options.config;
+  return checkInstallation;
+}
+
+export const getBlockChainNameFromId = (
+  chainId: string | number,
+  blockchains: BlockchainMeta[]
+): Network | null => {
+  chainId =
+    typeof chainId === 'string' && chainId.startsWith('0x')
+      ? parseInt(chainId)
+      : chainId;
+
+  /*
+   * Sometimes providers are passing `Network` as chainId.
+   * If chainId is a `Network`, we return itself.
+   */
+  const allNetworks = Object.values(Networks);
+  if (allNetworks.includes(String(chainId) as Networks)) {
+    return chainId as Networks;
+  }
+
+  if (chainId === 'Binance-Chain-Tigris') {
+    return Networks.BINANCE;
+  }
+  return (
+    blockchains
+      .filter((blockchainMeta) => !!blockchainMeta.chainId)
+      .find((blockchainMeta) => {
+        const blockchainChainId = blockchainMeta.chainId?.startsWith('0x')
+          ? parseInt(blockchainMeta.chainId)
+          : blockchainMeta.chainId;
+        return blockchainChainId == chainId;
+      })?.name || null
+  );
+};

package/src/legacy/mod.ts

@@ -0,0 +1,44 @@
+/*
+ * All the exported types/values from legacy should be prefixed with `Legacy`
+ * since they will be removed soon and isn't part of the main interface for this package.
+ */
+export type {
+  EventHandler as LegacyEventHandler,
+  State as LegacyState,
+  Options as LegacyOptions,
+} from './wallet.js';
+
+export type {
+  Connect as LegacyConnect,
+  Disconnect as LegacyDisconnect,
+  Subscribe as LegacySubscribe,
+  CanEagerConnect as LegacyCanEagerConnect,
+  SwitchNetwork as LegacySwitchNetwork,
+  Suggest as LegacySuggest,
+  CanSwitchNetwork as LegacyCanSwitchNetwork,
+  NamespaceData as LegacyNamespaceData,
+  ProviderInterface as LegacyProviderInterface,
+  NetworkProviderMap as LegacyNetworkProviderMap,
+  Network as LegacyNetwork,
+  WalletType as LegacyWalletType,
+  InstallObjects as LegacyInstallObjects,
+  WalletInfo as LegacyWalletInfo,
+  ConnectResult as LegacyConnectResult,
+  NamespaceInputForConnect as LegacyNamespaceInputForConnect,
+  NamespaceMeta as LegacyNamespaceMeta,
+} from './types.js';
+
+export { Events as LegacyEvents, Networks as LegacyNetworks } from './types.js';
+
+export { Persistor } from './persistor.js';
+export {
+  readAccountAddress as legacyReadAccountAddress,
+  getBlockChainNameFromId as legacyGetBlockChainNameFromId,
+  formatAddressWithNetwork as legacyFormatAddressWithNetwork,
+} from './helpers.js';
+export { default as LegacyWallet } from './wallet.js';
+
+export {
+  eagerConnectHandler as legacyEagerConnectHandler,
+  isEvmNamespace as legacyIsEvmNamespace,
+} from './utils.js';

package/src/legacy/persistor.ts

@@ -0,0 +1,19 @@
+export interface PersistStorage<T> {
+  getItem: (name: string) => T | null;
+  setItem: (name: string, value: T) => void;
+  removeItem: (name: string) => void;
+}
+
+export class Persistor<T> implements PersistStorage<T> {
+  getItem(name: string) {
+    const item = localStorage.getItem(name);
+    const parsedItem = item ? (JSON.parse(item) as T) : null;
+    return parsedItem;
+  }
+  setItem(name: string, value: T) {
+    localStorage.setItem(name, JSON.stringify(value));
+  }
+  removeItem(name: string) {
+    localStorage.removeItem(name);
+  }
+}

package/src/legacy/types.ts

@@ -0,0 +1,291 @@
+import type { State as WalletState } from './wallet.js';
+import type { Namespace } from '../namespaces/common/mod.js';
+import type { BlockchainMeta, SignerFactory } from 'rango-types';
+
+export enum Networks {
+  BTC = 'BTC',
+  BSC = 'BSC',
+  LTC = 'LTC',
+  THORCHAIN = 'THOR',
+  BCH = 'BCH',
+  BINANCE = 'BNB',
+  ETHEREUM = 'ETH',
+  POLYGON = 'POLYGON',
+  TERRA = 'TERRA',
+  POLKADOT = '',
+  TRON = 'TRON',
+  DOGE = 'DOGE',
+  HARMONY = 'HARMONY',
+  AVAX_CCHAIN = 'AVAX_CCHAIN',
+  FANTOM = 'FANTOM',
+  MOONBEAM = 'MOONBEAM',
+  ARBITRUM = 'ARBITRUM',
+  BOBA = 'BOBA',
+  OPTIMISM = 'OPTIMISM',
+  FUSE = 'FUSE',
+  CRONOS = 'CRONOS',
+  SOLANA = 'SOLANA',
+  MOONRIVER = 'MOONRIVER',
+  GNOSIS = 'GNOSIS',
+  COSMOS = 'COSMOS',
+  OSMOSIS = 'OSMOSIS',
+  AXELAR = 'AXELAR',
+  MARS = 'MARS',
+  STRIDE = 'STRIDE',
+  MAYA = 'MAYA',
+  AKASH = 'AKASH',
+  IRIS = 'IRIS',
+  PERSISTENCE = 'PERSISTENCE',
+  SENTINEL = 'SENTINEL',
+  REGEN = 'REGEN',
+  CRYPTO_ORG = 'CRYPTO_ORG',
+  SIF = 'SIF',
+  CHIHUAHUA = 'CHIHUAHUA',
+  JUNO = 'JUNO',
+  KUJIRA = 'KUJIRA',
+  STARNAME = 'STARNAME',
+  COMDEX = 'COMDEX',
+  STARGAZE = 'STARGAZE',
+  DESMOS = 'DESMOS',
+  BITCANNA = 'BITCANNA',
+  SECRET = 'SECRET',
+  INJECTIVE = 'INJECTIVE',
+  LUMNETWORK = 'LUMNETWORK',
+  BANDCHAIN = 'BANDCHAIN',
+  EMONEY = 'EMONEY',
+  BITSONG = 'BITSONG',
+  KI = 'KI',
+  MEDIBLOC = 'MEDIBLOC',
+  KONSTELLATION = 'KONSTELLATION',
+  UMEE = 'UMEE',
+  STARKNET = 'STARKNET',
+  TON = 'TON',
+  BASE = 'BASE',
+  SUI = 'SUI',
+  // Using instead of null
+  Unknown = 'Unkown',
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type InstanceType = any;
+
+export type NamespaceData = {
+  namespace: Namespace;
+  derivationPath?: string;
+};
+
+export type WalletType = string;
+export type Network = string;
+
+export type InstallObjects = {
+  CHROME?: string;
+  FIREFOX?: string;
+  EDGE?: string;
+  BRAVE?: string;
+  DEFAULT: string;
+};
+
+export type NamespaceMeta = {
+  label: string;
+  /**
+   * By using a matched `blockchain.name` (in meta) and `id`, we show logo in Namespace modal
+   * e.g. ETH
+   */
+  id: string;
+  value: Namespace;
+  unsupported?: boolean;
+  getSupportedChains: (chains: BlockchainMeta[]) => BlockchainMeta[];
+};
+
+interface NeedsNamespace {
+  selection: 'single' | 'multiple';
+  data: NamespaceMeta[];
+}
+
+interface NeedsDerivationPath {
+  data: {
+    id: string;
+    label: string;
+    namespace: Namespace;
+    generateDerivationPath: (index: string) => string;
+  }[];
+}
+
+export type WalletInfo = {
+  name: string;
+  img: string;
+  installLink: InstallObjects | string;
+  /**
+   * @deprecated we don't use this value anymore.
+   */
+  color: string;
+  supportedChains: BlockchainMeta[];
+  showOnMobile?: boolean;
+  isContractWallet?: boolean;
+  mobileWallet?: boolean;
+
+  needsDerivationPath?: NeedsDerivationPath;
+  needsNamespace?: NeedsNamespace;
+};
+
+export type State = {
+  [key: string]: WalletState | undefined;
+};
+
+export type ConnectResult = {
+  accounts: string[] | null;
+  network: Network | null;
+  provider: InstanceType;
+};
+
+export type Providers = { [type in WalletType]?: InstanceType };
+export type NetworkProviderMap = Map<Networks, unknown>;
+
+export enum Events {
+  CONNECTED = 'connected',
+  CONNECTING = 'connecting',
+  REACHABLE = 'reachable',
+  INSTALLED = 'installed',
+  ACCOUNTS = 'accounts',
+  NETWORK = 'network',
+  // Hub only events
+  NAMESPACE_DISCONNECTED = 'namespace_disconnected',
+
+  PROVIDER_DISCONNECTED = 'provider_disconnected',
+}
+
+export type ProviderConnectResult = {
+  accounts: string[];
+  chainId: string;
+  derivationPath?: string;
+};
+
+export type GetInstanceOptions = {
+  network?: Network;
+  currentProvider: InstanceType;
+  meta: BlockchainMeta[];
+  getState: () => WalletState;
+  /**
+   * We always get the instance once and reuse it whenever we needs. By using this option
+   * We can force the library to get a new instance and replace it with the old one.
+   *
+   * Originally, we used this option for wallet connect 1 and its switching network challenge.
+   */
+  force?: boolean;
+  updateChainId: (chainId: number | string) => void;
+};
+
+export type GetInstance =
+  | (() => InstanceType)
+  | ((options: GetInstanceOptions) => Promise<InstanceType>);
+
+export type TryGetInstance =
+  | (() => InstanceType)
+  | ((
+      options: Pick<GetInstanceOptions, 'force' | 'network'>
+    ) => Promise<InstanceType>);
+
+export type Connect = (options: {
+  instance: InstanceType;
+  network?: Network;
+  meta: BlockchainMeta[];
+  namespaces?: NamespaceData[];
+}) => Promise<ProviderConnectResult | ProviderConnectResult[]>;
+
+export type Disconnect = (options: {
+  instance: InstanceType;
+  destroyInstance: () => void;
+}) => Promise<void>;
+
+type CleanupSubscribe = () => void;
+
+export type Subscribe = (options: {
+  instance: InstanceType;
+  state: WalletState;
+  meta: BlockchainMeta[];
+  updateChainId: (chainId: string) => void;
+  updateAccounts: (accounts: string[], chainId?: string) => void;
+  connect: (network?: Network) => void;
+  disconnect: () => void;
+}) => CleanupSubscribe | void;
+
+export type SwitchNetwork = (options: {
+  instance: InstanceType;
+  network: Network;
+  meta: BlockchainMeta[];
+  newInstance?: TryGetInstance;
+  getState?: () => WalletState;
+  updateChainId: (chainId: string) => void;
+}) => Promise<void>;
+
+export type Suggest = (options: {
+  instance: InstanceType;
+  network: Network;
+  meta: BlockchainMeta[];
+}) => Promise<void>;
+
+export type CanSwitchNetwork = (options: {
+  network: Network;
+  meta: BlockchainMeta[];
+  provider: InstanceType;
+}) => boolean;
+
+export type CanEagerConnect = (options: {
+  instance: InstanceType;
+  meta: BlockchainMeta[];
+}) => Promise<boolean>;
+
+export type EagerConnectResult<I = unknown> = {
+  accounts: string[] | null;
+  network: string | null;
+  provider: I | null;
+};
+
+export interface WalletActions {
+  connect: Connect;
+  getInstance: InstanceType;
+  disconnect?: Disconnect;
+  subscribe?: Subscribe;
+  // unsubscribe, // coupled to subscribe.
+
+  // Optional, but should be provided at the same time.
+  suggest?: Suggest;
+  switchNetwork?: SwitchNetwork;
+  getSigners: (provider: InstanceType) => Promise<SignerFactory>;
+  canSwitchNetworkTo?: CanSwitchNetwork;
+  canEagerConnect?: CanEagerConnect;
+  getWalletInfo(allBlockChains: BlockchainMeta[]): WalletInfo;
+}
+
+export interface WalletConfig {
+  type: WalletType;
+  defaultNetwork?: Network;
+  checkInstallation?: boolean;
+  isAsyncInstance?: boolean;
+  isAsyncSwitchNetwork?: boolean;
+}
+
+export type WalletProviders = Map<
+  WalletType,
+  {
+    actions: WalletActions;
+    config: WalletConfig;
+  }
+>;
+
+export type ProviderInterface = { config: WalletConfig } & WalletActions;
+
+// it comes from wallets.ts and `connect`
+type NetworkTypeFromLegacyConnect = Network | undefined;
+
+export type NamespaceInputForConnect<T extends Namespace = Namespace> = {
+  /**
+   * By default, you should specify namespace (e.g. evm).
+   */
+  namespace: T;
+  /**
+   * In some cases, we need to connect a specific network on a namespace. e.g. Polygon on EVM.
+   */
+  network: NetworkTypeFromLegacyConnect;
+  derivationPath?: string;
+};

package/src/legacy/utils.ts

@@ -0,0 +1,20 @@
+import type { NamespaceInputForConnect } from './types.js';
+
+export async function eagerConnectHandler<R = unknown>(params: {
+  canEagerConnect: () => Promise<boolean>;
+  connectHandler: () => Promise<R>;
+  providerName: string;
+}) {
+  // Check if we can eagerly connect to the wallet
+  if (await params.canEagerConnect()) {
+    // Connect to wallet as usual
+    return await params.connectHandler();
+  }
+  throw new Error(`can't restore connection for ${params.providerName}.`);
+}
+
+export function isEvmNamespace(
+  namespace: NamespaceInputForConnect
+): namespace is NamespaceInputForConnect<'EVM'> {
+  return namespace.namespace === 'EVM';
+}