@hub3js/core 0.58.2-next.0

package/src/namespaces/evm/hooks.ts

@@ -0,0 +1,43 @@
+import type { EIP1193EventMap } from './eip1193.js';
+import type { EvmActions, ProviderAPI } from './types.js';
+import type { Subscriber, SubscriberCleanUp } from '../../mod.js';
+
+import { builders } from './mod.js';
+
+export function changeAccountSubscriber(
+  instance: () => ProviderAPI,
+): [Subscriber<EvmActions>, SubscriberCleanUp<EvmActions>] {
+  return builders.changeAccountSubscriber(instance).build();
+}
+
+export function changeChainSubscriber(
+  instance: () => ProviderAPI,
+): [Subscriber<EvmActions>, SubscriberCleanUp<EvmActions>] {
+  let eventCallback: EIP1193EventMap['chainChanged'];
+
+  return [
+    (context) => {
+      const evmInstance = instance();
+
+      if (!evmInstance) {
+        throw new Error(
+          'Trying to subscribe to your EVM wallet, but seems its instance is not available.',
+        );
+      }
+
+      const [, setState] = context.state();
+
+      eventCallback = async (chainId: string) => {
+        setState('network', chainId);
+      };
+      evmInstance.on('chainChanged', eventCallback);
+    },
+    () => {
+      const evmInstance = instance();
+
+      if (eventCallback && evmInstance) {
+        evmInstance.removeListener('chainChanged', eventCallback);
+      }
+    },
+  ];
+}

package/src/namespaces/evm/mod.ts

@@ -0,0 +1,10 @@
+export * as actions from './actions.js';
+export * as hooks from './hooks.js';
+export * as after from './after.js';
+export * as and from './and.js';
+export * as before from './before.js';
+export * as utils from './utils.js';
+export * as builders from './builders.js';
+
+export type { EvmActions, ProviderAPI, Chain, ChainId } from './types.js';
+export { CAIP_NAMESPACE, CAIP_ETHEREUM_CHAIN_ID } from './constants.js';

package/src/namespaces/evm/types.ts

@@ -0,0 +1,36 @@
+import type { AddEthereumChainParameter, EIP1193Provider } from './eip1193.js';
+import type { AccountsWithActiveChain } from '../../types/accounts.js';
+import type {
+  AutoImplementedActionsByRecommended,
+  CommonActions,
+} from '../common/types.js';
+import type { BlockchainMeta } from 'rango-types';
+
+export interface EvmActions
+  extends AutoImplementedActionsByRecommended, CommonActions {
+  connect: (
+    chain?: Chain | ChainId,
+    options?: ConnectOptions,
+  ) => Promise<AccountsWithActiveChain>;
+  canEagerConnect: () => Promise<boolean>;
+  canSwitchNetwork: (params: CanSwitchNetworkParams) => boolean;
+  getChainId: () => Promise<`0x${string}`>;
+}
+type CanSwitchNetworkParams = {
+  network: string;
+  supportedChains: BlockchainMeta[];
+};
+
+export type ProviderAPI = EIP1193Provider;
+// A 0x-prefixed hexadecimal string
+export type ChainId = string;
+export type Chain = AddEthereumChainParameter;
+export type ProviderAccounts = {
+  accounts: string[];
+  chainId: ChainId;
+};
+export type ConnectOptions = {
+  switchOrAddNetwork?: (instance: ProviderAPI, chain: ChainId | Chain) => void;
+  getAccounts?: (provider: ProviderAPI) => Promise<ProviderAccounts>;
+  derivationPath?: string;
+};

package/src/namespaces/evm/utils.ts

@@ -0,0 +1,106 @@
+import type { Chain, ChainId, ProviderAPI } from './types.js';
+import type { CaipAccount } from '../../types/accounts.js';
+
+import { AccountId } from 'caip';
+import { type BlockchainMeta, evmBlockchains } from 'rango-types';
+
+import { CAIP_NAMESPACE } from './constants.js';
+
+const CHAIN_ID_RADIX = 16;
+
+export async function getAccounts(provider: ProviderAPI) {
+  const [accounts, chainId] = await Promise.all([
+    provider.request({ method: 'eth_requestAccounts' }),
+    provider.request({ method: 'eth_chainId' }),
+  ]);
+  /*
+   * Trust Wallet Compatibility Fix:
+   * Trust Wallet's in-app browser has been observed to return the `chainId` as a
+   * number (e.g., 1) rather than the standard hexadecimal string (e.g., "0x1").
+   * This code block standardizes the `chainId` to the required hex format to
+   * prevent downstream errors.
+   */
+  let standardChainId = chainId;
+  if (typeof standardChainId === 'number') {
+    standardChainId = `0x${Number(chainId).toString(CHAIN_ID_RADIX)}`;
+  }
+
+  return {
+    accounts,
+    chainId: standardChainId,
+  };
+}
+
+export async function suggestNetwork(instance: ProviderAPI, chain: Chain) {
+  return await instance.request({
+    method: 'wallet_addEthereumChain',
+    params: [chain],
+  });
+}
+
+export async function switchNetwork(instance: ProviderAPI, chainId: ChainId) {
+  return await instance.request({
+    method: 'wallet_switchEthereumChain',
+    params: [{ chainId: chainId }],
+  });
+}
+export function filterAndGetEvmBlockchainNames(meta: BlockchainMeta[]) {
+  return evmBlockchains(meta).map((blockchain) => blockchain.name);
+}
+export async function switchOrAddNetwork(
+  instance: ProviderAPI,
+  chain: ChainId | Chain,
+) {
+  try {
+    const chainId = typeof chain === 'string' ? chain : chain.chainId;
+    await switchNetwork(instance, chainId);
+  } catch (switchError) {
+    const error = switchError as { code: number };
+
+    /*
+     * Error code 4902 is used by MetaMask to indicate that the requested chain has not been added to the wallet.
+     * This code is not part of the official EIP-1193 spec (https://eips.ethereum.org/EIPS/eip-1193#supported-rpc-methods),
+     * so other providers may use a different code or behavior for the same condition.
+     */
+    const NOT_FOUND_CHAIN_ERROR_CODE = 4902;
+    if (
+      typeof chain !== 'string' &&
+      (error.code === NOT_FOUND_CHAIN_ERROR_CODE || !error.code)
+    ) {
+      /*
+       * Note: on WalletConnect `code` is undefined so we have to use !switchError.code as fallback.
+       * This error code indicates that the chain has not been added to wallet.
+       */
+      await suggestNetwork(instance, chain);
+      return;
+    }
+    throw switchError;
+  }
+}
+
+const EIP_1193_USER_REJECTION_ERROR_CODE = 4001;
+export function isUserRejectionError(error: unknown): boolean {
+  // EIP-1193 user rejection error can be in error.code or error.cause.code
+  if (typeof error === 'object' && error !== null) {
+    const code = (error as { code?: number }).code;
+    const causeCode = (error as { cause?: { code?: number } }).cause?.code;
+    return (
+      code === EIP_1193_USER_REJECTION_ERROR_CODE ||
+      causeCode === EIP_1193_USER_REJECTION_ERROR_CODE
+    );
+  }
+  return false;
+}
+
+export function formatAccountsToCAIP(accounts: string[], chainId: string) {
+  return accounts.map(
+    (account) =>
+      AccountId.format({
+        address: account,
+        chainId: {
+          namespace: CAIP_NAMESPACE,
+          reference: chainId,
+        },
+      }) as CaipAccount,
+  );
+}

package/src/namespaces/solana/actions.ts

@@ -0,0 +1,44 @@
+import type { ProviderAPI, SolanaActions } from './types.js';
+import type { Context } from '../../hub/namespaces/mod.js';
+import type { FunctionWithContext } from '../../types/actions.js';
+
+import { recommended as commonRecommended } from '../common/actions.js';
+
+import { formatAccountsToCAIP, getAccounts } from './utils.js';
+
+export const recommended = [...commonRecommended];
+
+export function connect(
+  instance: () => ProviderAPI,
+): FunctionWithContext<SolanaActions['connect'], Context> {
+  return async () => {
+    const solanaInstance = instance();
+    const result = await getAccounts(solanaInstance);
+
+    if (Array.isArray(result)) {
+      throw new Error(
+        'Expecting solana response to be a single value, not an array.',
+      );
+    }
+
+    return formatAccountsToCAIP(result.accounts);
+  };
+}
+export function canEagerConnect(instance: () => ProviderAPI) {
+  return async () => {
+    const solanaInstance = instance();
+
+    if (!solanaInstance) {
+      throw new Error(
+        'Trying to eagerly connect to your Solana wallet, but seems its instance is not available.',
+      );
+    }
+
+    try {
+      const result = await solanaInstance.connect({ onlyIfTrusted: true });
+      return !!result;
+    } catch {
+      return false;
+    }
+  };
+}

package/src/namespaces/solana/after.ts

@@ -0,0 +1,3 @@
+import { recommended as commonRecommended } from '../common/after.js';
+
+export const recommended = [...commonRecommended];

package/src/namespaces/solana/and.ts

@@ -0,0 +1,5 @@
+import { connectAndUpdateStateForSingleNetwork } from '../common/mod.js';
+
+export const recommended = [
+  ['connect', connectAndUpdateStateForSingleNetwork] as const,
+];

package/src/namespaces/solana/before.ts

@@ -0,0 +1,3 @@
+import { recommended as commonRecommended } from '../common/before.js';
+
+export const recommended = [...commonRecommended];

package/src/namespaces/solana/builders.ts

@@ -0,0 +1,40 @@
+import type { ProviderAPI, SolanaActions } from './types.js';
+
+import { ActionBuilder } from '../../mod.js';
+import { ChangeAccountSubscriberBuilder } from '../common/hooks/changeAccountSubscriber.js';
+import {
+  connectAndUpdateStateForSingleNetwork,
+  intoConnecting,
+  intoConnectionFinished,
+} from '../common/mod.js';
+
+import { formatAccountsToCAIP } from './utils.js';
+
+// Actions
+export const connect = () =>
+  new ActionBuilder<SolanaActions, 'connect'>('connect')
+    .and(connectAndUpdateStateForSingleNetwork)
+    .before(intoConnecting)
+    .after(intoConnectionFinished);
+
+// Hooks
+export const changeAccountSubscriber = (getInstance: () => ProviderAPI) =>
+  new ChangeAccountSubscriberBuilder<string, ProviderAPI, SolanaActions>()
+    .getInstance(getInstance)
+    /*
+     * In some wallets, when a user switches to an account not yet connected to the dApp, it returns null.
+     * A null value indicates no access to the account, requiring a disconnect and user reconnection.
+     */
+    .onSwitchAccount((event, context) => {
+      if (!event.payload) {
+        context.action('disconnect');
+        event.preventDefault();
+      }
+    })
+    .format(async (_, accounts) => formatAccountsToCAIP([accounts]))
+    .addEventListener((instance, callback) => {
+      instance.on('accountChanged', callback);
+    })
+    .removeEventListener((instance, callback) => {
+      instance.off('accountChanged', callback);
+    });

package/src/namespaces/solana/constants.ts

@@ -0,0 +1,2 @@
+export const CAIP_NAMESPACE = 'solana';
+export const CAIP_SOLANA_CHAIN_ID = '5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp';

package/src/namespaces/solana/hooks.ts

@@ -0,0 +1,10 @@
+import type { ProviderAPI, SolanaActions } from './types.js';
+import type { Subscriber, SubscriberCleanUp } from '../../mod.js';
+
+import { builders } from './mod.js';
+
+export function changeAccountSubscriber(
+  instance: () => ProviderAPI,
+): [Subscriber<SolanaActions>, SubscriberCleanUp<SolanaActions>] {
+  return builders.changeAccountSubscriber(instance).build();
+}

package/src/namespaces/solana/mod.ts

@@ -0,0 +1,10 @@
+export * as actions from './actions.js';
+export * as hooks from './hooks.js';
+export * as after from './after.js';
+export * as and from './and.js';
+export * as before from './before.js';
+export * as builders from './builders.js';
+export * as utils from './utils.js';
+
+export type { ProviderAPI, SolanaActions } from './types.js';
+export { CAIP_NAMESPACE, CAIP_SOLANA_CHAIN_ID } from './constants.js';

package/src/namespaces/solana/types.ts

@@ -0,0 +1,25 @@
+import type { Accounts } from '../../types/accounts.js';
+import type {
+  AutoImplementedActionsByRecommended,
+  CommonActions,
+} from '../common/types.js';
+
+export interface SolanaActions
+  extends AutoImplementedActionsByRecommended, CommonActions {
+  connect: (options?: ConnectOptions) => Promise<Accounts>;
+  canEagerConnect: () => Promise<boolean>;
+}
+
+/*
+ *
+ * TODO: That would be better to define a type for Solana injected wallets.
+ * They have something called [Wallet Standard](https://github.com/wallet-standard/wallet-standard) but not sure all the Solana wallets support that (Phantom do).
+ * If Phantom's interface is what Solana wallets are supporting, another option would be define that type here.
+ *
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type ProviderAPI = Record<string, any>;
+
+export type ConnectOptions = {
+  derivationPath?: string;
+};

package/src/namespaces/solana/utils.ts

@@ -0,0 +1,36 @@
+import type { ProviderAPI } from './types.js';
+import type { CaipAccount } from '../../types/accounts.js';
+
+import { AccountId } from 'caip';
+
+import { LegacyNetworks } from '../../legacy/mod.js';
+
+import { CAIP_NAMESPACE, CAIP_SOLANA_CHAIN_ID } from './constants.js';
+
+export async function getAccounts(provider: ProviderAPI) {
+  const solanaResponse = await provider.connect();
+  /*
+   * Fallback for wallets like Coinbase that return no response on connect.
+   * If solanaResponse is undefined, use the provider's publicKey directly.
+   */
+  const account = solanaResponse
+    ? solanaResponse.publicKey.toString()
+    : provider.publicKey.toString();
+  return {
+    accounts: [account],
+    chainId: LegacyNetworks.SOLANA,
+  };
+}
+
+export function formatAccountsToCAIP(accounts: string[]) {
+  return accounts.map(
+    (account) =>
+      AccountId.format({
+        address: account.toString(),
+        chainId: {
+          namespace: CAIP_NAMESPACE,
+          reference: CAIP_SOLANA_CHAIN_ID,
+        },
+      }) as CaipAccount,
+  );
+}

package/src/namespaces/starknet/actions.ts

@@ -0,0 +1,19 @@
+import type { ProviderAPI } from './types.js';
+
+import { recommended as commonRecommended } from '../common/actions.js';
+
+export const recommended = [...commonRecommended];
+
+export function canEagerConnect(instance: () => ProviderAPI) {
+  return async () => {
+    const starknetInstance = instance();
+
+    if (!starknetInstance) {
+      throw new Error(
+        'Trying to eagerly connect to your Starknet wallet, but seems its instance is not available.',
+      );
+    }
+
+    return starknetInstance.isPreauthorized();
+  };
+}

package/src/namespaces/starknet/after.ts

@@ -0,0 +1,3 @@
+import { recommended as commonRecommended } from '../common/after.js';
+
+export const recommended = [...commonRecommended];

package/src/namespaces/starknet/and.ts

@@ -0,0 +1,5 @@
+import { connectAndUpdateStateForSingleNetwork } from '../common/mod.js';
+
+export const recommended = [
+  ['connect', connectAndUpdateStateForSingleNetwork] as const,
+];

package/src/namespaces/starknet/before.ts

@@ -0,0 +1,3 @@
+import { recommended as commonRecommended } from '../common/before.js';
+
+export const recommended = [...commonRecommended];

package/src/namespaces/starknet/builders.ts

@@ -0,0 +1,18 @@
+import type { StarknetActions } from './types.js';
+
+import { ActionBuilder } from '../../mod.js';
+import {
+  connectAndUpdateStateForSingleNetwork,
+  intoConnecting,
+  intoConnectionFinished,
+} from '../common/mod.js';
+
+// Actions
+export const connect = () =>
+  new ActionBuilder<StarknetActions, 'connect'>('connect')
+    .and(connectAndUpdateStateForSingleNetwork)
+    .before(intoConnecting)
+    .after(intoConnectionFinished);
+
+export const canEagerConnect = () =>
+  new ActionBuilder<StarknetActions, 'canEagerConnect'>('canEagerConnect');

package/src/namespaces/starknet/constants.ts

@@ -0,0 +1,8 @@
+/*
+ * TODO: I couldn't found starknet in caip
+ * @see https://namespaces.chainagnostic.org/
+ */
+
+// if the value needs to be change make sure you will update mapCaipNamespaceToLegacyNetworkName as well
+export const CAIP_NAMESPACE = 'starknet';
+export const CAIP_STARKNET_CHAIN_ID = 'SN_MAIN';

package/src/namespaces/starknet/mod.ts

@@ -0,0 +1,9 @@
+export * as actions from './actions.js';
+export * as after from './after.js';
+export * as and from './and.js';
+export * as before from './before.js';
+export * as builders from './builders.js';
+export * as utils from './utils.js';
+
+export type { ProviderAPI, StarknetActions } from './types.js';
+export { CAIP_NAMESPACE, CAIP_STARKNET_CHAIN_ID } from './constants.js';

package/src/namespaces/starknet/types.ts

@@ -0,0 +1,18 @@
+import type { Accounts } from '../../types/accounts.js';
+import type {
+  AutoImplementedActionsByRecommended,
+  CommonActions,
+} from '../common/types.js';
+
+export interface StarknetActions
+  extends AutoImplementedActionsByRecommended, CommonActions {
+  connect: (options?: ConnectOptions) => Promise<Accounts>;
+  canEagerConnect: () => Promise<boolean>;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type ProviderAPI = Record<string, any>;
+
+export type ConnectOptions = {
+  derivationPath?: string;
+};

package/src/namespaces/starknet/utils.ts

@@ -0,0 +1,35 @@
+import type { ProviderAPI } from './types.js';
+import type { CaipAccount } from '../../types/accounts.js';
+
+import { AccountId } from 'caip';
+
+import { LegacyNetworks } from '../../legacy/mod.js';
+
+import { CAIP_NAMESPACE, CAIP_STARKNET_CHAIN_ID } from './constants.js';
+
+export async function getAccounts(provider: ProviderAPI) {
+  const starknetResponse = await provider.connect();
+  /*
+   * Fallback for wallets that return no response on connect.
+   */
+  const account = starknetResponse
+    ? starknetResponse.publicKey.toString()
+    : provider.publicKey.toString();
+  return {
+    accounts: [account],
+    chainId: LegacyNetworks.SOLANA,
+  };
+}
+
+export function formatAccountsToCAIP(accounts: string[]) {
+  return accounts.map(
+    (account) =>
+      AccountId.format({
+        address: account.toString(),
+        chainId: {
+          namespace: CAIP_NAMESPACE,
+          reference: CAIP_STARKNET_CHAIN_ID,
+        },
+      }) as CaipAccount,
+  );
+}

package/src/namespaces/sui/actions.ts

@@ -0,0 +1,27 @@
+import type { SuiActions } from './types.js';
+import type { CanEagerConnect } from '../../hub/namespaces/types.js';
+
+import { getInstanceOrThrow } from './mod.js';
+
+interface CanEagerConnectParams {
+  name: string;
+}
+export function canEagerConnect(
+  params: CanEagerConnectParams,
+): CanEagerConnect<SuiActions> {
+  return async () => {
+    const wallet = getInstanceOrThrow(params.name);
+
+    try {
+      const connectResult = await wallet.features['standard:connect'].connect({
+        silent: true,
+      });
+      if (connectResult.accounts.length) {
+        return true;
+      }
+      return false;
+    } catch {
+      return false;
+    }
+  };
+}

package/src/namespaces/sui/builders.ts

@@ -0,0 +1,77 @@
+import type {
+  ChangeAccountSubscriberParams,
+  ProviderAPI,
+  SuiActions,
+} from './types.js';
+import type { WalletAccount } from '@mysten/wallet-standard';
+
+import { ActionBuilder } from '../../mod.js';
+import { CAIP } from '../../utils/mod.js';
+import { ChangeAccountSubscriberBuilder } from '../common/hooks/changeAccountSubscriber.js';
+import {
+  type CaipAccount,
+  connectAndUpdateStateForSingleNetwork,
+  intoConnecting,
+  intoConnectionFinished,
+} from '../common/mod.js';
+
+import { CAIP_NAMESPACE, CAIP_SUI_CHAIN_ID } from './constants.js';
+import { formatAccountsToCAIP, getInstanceOrThrow } from './utils.js';
+
+// Actions
+interface ConnectParams {
+  name: string;
+}
+
+export const connect = (params: ConnectParams) =>
+  new ActionBuilder<SuiActions, 'connect'>('connect')
+    .action(async function () {
+      const wallet = getInstanceOrThrow(params.name);
+      const features = wallet.features;
+
+      const result = await features['standard:connect'].connect();
+
+      const accounts = result.accounts.map((account) => {
+        return CAIP.AccountId.format({
+          address: account.address,
+          chainId: {
+            namespace: CAIP_NAMESPACE,
+            reference: CAIP_SUI_CHAIN_ID,
+          },
+        }) as CaipAccount;
+      });
+
+      return accounts;
+    })
+    .and(connectAndUpdateStateForSingleNetwork)
+    .before(intoConnecting)
+    .after(intoConnectionFinished);
+
+export const canEagerConnect = () =>
+  new ActionBuilder<SuiActions, 'canEagerConnect'>('canEagerConnect');
+
+// Hooks
+export const changeAccountSubscriber = (
+  params: ChangeAccountSubscriberParams,
+) =>
+  new ChangeAccountSubscriberBuilder<
+    { accounts: readonly WalletAccount[] },
+    ProviderAPI,
+    SuiActions
+  >()
+    .getInstance(() => getInstanceOrThrow(params.name))
+    /*
+     * In some wallets, when a user switches to an account not yet connected to the dApp, it returns null.
+     * A null value indicates no access to the account, requiring a disconnect and user reconnection.
+     */
+    .onSwitchAccount((event, context) => {
+      if (!event.payload.accounts?.length) {
+        context.action('disconnect');
+        event.preventDefault();
+      }
+    })
+    .format(async (_, event) => formatAccountsToCAIP(event.accounts))
+    .addEventListener((instance, callback) =>
+      instance.features['standard:events'].on('change', callback),
+    )
+    .removeEventListener((_, __) => {});

package/src/namespaces/sui/constants.ts

@@ -0,0 +1,8 @@
+/*
+ * TODO: I couldn't found sui in caip
+ * @see https://namespaces.chainagnostic.org/
+ */
+
+// if the value neeeds to be change make sure you will update mapCaipNamespaceToLegacyNetworkName as well
+export const CAIP_NAMESPACE = 'sui';
+export const CAIP_SUI_CHAIN_ID = 'sui';

package/src/namespaces/sui/hooks.ts

@@ -0,0 +1,10 @@
+import type { ChangeAccountSubscriberParams, SuiActions } from './types.js';
+import type { Subscriber, SubscriberCleanUp } from '../../mod.js';
+
+import { builders } from './mod.js';
+
+export function changeAccountSubscriber(
+  params: ChangeAccountSubscriberParams,
+): [Subscriber<SuiActions>, SubscriberCleanUp<SuiActions>] {
+  return builders.changeAccountSubscriber({ name: params.name }).build();
+}

package/src/namespaces/sui/mod.ts

@@ -0,0 +1,8 @@
+export type { ProviderAPI, SuiActions } from './types.js';
+
+export * as actions from './actions.js';
+export * as builders from './builders.js';
+export * as hooks from './hooks.js';
+export { getInstanceOrThrow, getInstance } from './utils.js';
+
+export { CAIP_NAMESPACE, CAIP_SUI_CHAIN_ID } from './constants.js';