@swapkit/helpers 4.4.5 → 4.5.2

package/src/utils/chains.ts

@@ -0,0 +1,100 @@
+import { Chain, CosmosChains, EVMChains, type StagenetChain, StagenetChains, UTXOChains } from "@swapkit/types";
+import { match } from "ts-pattern";
+import { SKConfig } from "../modules/swapKitConfig";
+import { SwapKitError } from "../modules/swapKitError";
+import { warnOnce } from "./others";
+
+function getRpcBody(chain: Chain | StagenetChain) {
+  return match(chain)
+    .with(...EVMChains, () => ({ id: 1, jsonrpc: "2.0", method: "eth_blockNumber", params: [] }))
+    .with(...UTXOChains, () => ({ id: "test", jsonrpc: "1.0", method: "getblockchaininfo", params: [] }))
+    .with(...CosmosChains, ...StagenetChains, () => ({ id: 1, jsonrpc: "2.0", method: "status", params: {} }))
+    .with(Chain.Polkadot, Chain.Chainflip, () => ({ id: 1, jsonrpc: "2.0", method: "system_health", params: [] }))
+    .with(Chain.Solana, () => ({ id: 1, jsonrpc: "2.0", method: "getHealth" }))
+    .with(Chain.Sui, () => ({ id: 1, jsonrpc: "2.0", method: "sui_getSystemState", params: [] }))
+    .with(Chain.Ton, () => ({ id: 1, jsonrpc: "2.0", method: "getAddressInformation", params: { address: "" } }))
+    .with(Chain.Tron, Chain.Radix, () => "")
+    .with(Chain.Near, () => ({ id: "dontcare", jsonrpc: "2.0", method: "status", params: [] }))
+    .with(Chain.Ripple, () => ({ id: 1, jsonrpc: "2.0", method: "ping", params: [{}] }))
+    .otherwise(() => {
+      throw new SwapKitError("helpers_chain_not_supported", { chain });
+    });
+}
+
+function getChainStatusEndpoint(chain: Chain | StagenetChain) {
+  return match(chain)
+    .with(Chain.Radix, () => "/status/network-configuration")
+    .with(Chain.Tron, () => "/wallet/getnowblock")
+    .otherwise(() => "");
+}
+
+async function testRPCConnection(chain: Chain | StagenetChain, url: string) {
+  try {
+    const endpoint = url.startsWith("wss") ? url.replace("wss", "https") : url;
+    const response = await fetch(`${endpoint}${getChainStatusEndpoint(chain)}`, {
+      body: JSON.stringify(getRpcBody(chain)),
+      headers: { "Content-Type": "application/json" },
+      method: "POST",
+      signal: AbortSignal.timeout(3000),
+    });
+
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+
+const rpcCache = new Map<Chain | StagenetChain, { timestamp: number; url: string }>();
+const rpcCacheTTL = 1000 * 60 * 2; // 2 minutes
+
+export async function getRPCUrl(chain: Chain | StagenetChain) {
+  const { isStagenet } = SKConfig.get("envs");
+  const [rpcUrl = "", ...fallbackUrls] = SKConfig.get("rpcUrls")[chain];
+
+  if (!rpcUrl) {
+    warnOnce({
+      condition: true,
+      id: "helpers_chain_no_public_or_set_rpc_url",
+      warning: `No public or set RPC URL found for chain. Please ensure you configured rpcUrls for ${chain}.`,
+    });
+    throw new SwapKitError("helpers_chain_no_public_or_set_rpc_url", { chain });
+  }
+
+  if (isStagenet) return rpcUrl;
+
+  const cached = rpcCache.get(chain);
+  if (cached && Date.now() - cached.timestamp < rpcCacheTTL) {
+    return cached.url;
+  }
+
+  const primaryIsWorking = await testRPCConnection(chain, rpcUrl);
+
+  if (!primaryIsWorking) {
+    for (const fallbackUrl of fallbackUrls) {
+      const fallbackIsWorking = await testRPCConnection(chain, fallbackUrl);
+
+      if (fallbackIsWorking) {
+        rpcCache.set(chain, { timestamp: Date.now(), url: fallbackUrl });
+        return fallbackUrl;
+      }
+    }
+  }
+
+  rpcCache.set(chain, { timestamp: Date.now(), url: rpcUrl });
+  return rpcUrl;
+}
+
+/**
+ * @deprecated
+ * RPC URLs are now managed dynamically via SKConfig.
+ * Please use static { rpcUrls, fallbackRpcUrls } SwapKit init config or dynamic SKConfig.setRpcUrl/setFallbackRpcUrl to configure RPC endpoints.
+ * This function is obsolete and will be removed in a future release.
+ */
+export function initializeRPCUrlsWithFallback(_chains: never) {
+  warnOnce({
+    condition: true,
+    id: "initializeRPCUrlsWithFallback",
+    warning:
+      "initializeRPCUrlsWithFallback is deprecated. Use static { rpcUrls, fallbackRpcUrls } SwapKit init config or dynamic SKConfig.setRpcUrl/setFallbackRpcUrl to configure RPC endpoints.",
+  });
+}

package/src/utils/derivationPath.ts

@@ -0,0 +1,101 @@
+import { Chain, type EVMChain, EVMChains } from "@swapkit/types";
+import { type DerivationPathArray, NetworkDerivationPath } from "../types";
+
+type Params = {
+  chain: Chain;
+  index: number;
+  addressIndex?: number;
+  type?: "legacy" | "ledgerLive" | "nativeSegwitMiddleAccount" | "segwit" | "account";
+};
+
+export function updateDerivationPath(
+  path: DerivationPathArray,
+  params: { index: number } | { account: number } | { change: number },
+) {
+  if ("index" in params) {
+    const newPath = [...path.slice(0, path.length - 1), params.index];
+    return newPath as DerivationPathArray;
+  }
+
+  if ("change" in params) {
+    const [network, chainId, account, , index] = path;
+    return [network, chainId, account, params.change, index] as DerivationPathArray;
+  }
+
+  if ("account" in params) {
+    const [network, chainId, , change, index] = path;
+    return [network, chainId, params.account, change, index] as DerivationPathArray;
+  }
+
+  return path;
+}
+
+export function derivationPathToString([network, chainId, account, change, index]:
+  | [number, number, number, number?, number?]
+  | [number, number, number, number, number?]
+  | DerivationPathArray) {
+  const shortPath = typeof index !== "number";
+  const accountPath = typeof change !== "number";
+
+  if (accountPath) {
+    return `m/${network}'/${chainId}'/${account}'`;
+  }
+
+  return `m/${network}'/${chainId}'/${account}'/${change}${shortPath ? "" : `/${index}`}`;
+}
+
+// TODO @towan - sort this out and make it more readable
+export function getDerivationPathFor({ chain, index, addressIndex = 0, type }: Params) {
+  if (EVMChains.includes(chain as EVMChain)) {
+    if (type && ["legacy", "account"].includes(type)) {
+      return [44, 60, 0, index];
+    }
+
+    if (type === "ledgerLive") {
+      return [44, 60, index, 0, addressIndex] as DerivationPathArray;
+    }
+
+    return updateDerivationPath(NetworkDerivationPath[chain], { index });
+  }
+
+  if (chain === Chain.Solana) {
+    if (type === "account") return [44, 501, 0, index];
+    return updateDerivationPath(NetworkDerivationPath[chain], { index });
+  }
+
+  const chainId = chain === Chain.Litecoin ? 2 : 0;
+
+  switch (type) {
+    case "nativeSegwitMiddleAccount":
+      return [84, chainId, index, 0, addressIndex];
+    case "segwit":
+      return [49, chainId, 0, 0, index];
+    case "legacy":
+      return [44, chainId, 0, 0, index];
+    default:
+      return updateDerivationPath(NetworkDerivationPath[chain], { index });
+  }
+}
+
+export function getWalletFormatFor(path: string) {
+  const [_, purpose, chainId] = path.split("/").map((p) => Number.parseInt(p, 10));
+
+  if (chainId === 145) "cashaddr";
+
+  switch (purpose) {
+    case 44:
+      return "legacy";
+    case 49:
+      return "p2sh";
+    default:
+      return "bech32";
+  }
+}
+
+export const DerivationPath: Record<Chain, string> = Object.keys(NetworkDerivationPath).reduce(
+  (acc, key) => {
+    acc[key as Chain] = derivationPathToString(NetworkDerivationPath[key as Chain]);
+    return acc;
+  },
+  {} as Record<Chain, string>,
+);

package/src/utils/explorerUrls.ts

@@ -0,0 +1,32 @@
+import { Chain, CosmosChains, EVMChains, getChainConfig, SubstrateChains, UTXOChains } from "@swapkit/types";
+import { match } from "ts-pattern";
+
+export function getExplorerTxUrl({ chain, txHash }: { txHash: string; chain: Chain }) {
+  const { explorerUrl } = getChainConfig(chain);
+
+  return match(chain)
+    .with(
+      ...CosmosChains,
+      Chain.Solana,
+      () => `${explorerUrl}/tx/${txHash.startsWith("0x") ? txHash.slice(2) : txHash}`,
+    )
+    .with(
+      ...EVMChains,
+      ...SubstrateChains,
+      () => `${explorerUrl}/tx/${txHash.startsWith("0x") ? txHash : `0x${txHash}`}`,
+    )
+    .with(...UTXOChains, Chain.Radix, Chain.Tron, () => `${explorerUrl}/transaction/${txHash.toLowerCase()}`)
+    .with(Chain.Near, () => `${explorerUrl}/txns/${txHash}`)
+    .with(Chain.Ripple, () => `${explorerUrl}/transactions/${txHash}`)
+    .with(Chain.Sui, () => `${explorerUrl}/txblock/${txHash}`)
+    .with(Chain.Cardano, Chain.Ton, () => `${explorerUrl}/tx/${txHash}`)
+    .otherwise(() => "");
+}
+
+export function getExplorerAddressUrl({ chain, address }: { address: string; chain: Chain }) {
+  const { explorerUrl } = getChainConfig(chain);
+
+  return match(chain)
+    .with(Chain.Solana, Chain.Sui, Chain.Radix, () => `${explorerUrl}/account/${address}`)
+    .otherwise(() => `${explorerUrl}/address/${address}`);
+}

package/src/utils/liquidity.ts

@@ -0,0 +1,150 @@
+import { Chain, getChainConfig } from "@swapkit/types";
+import { SwapKitNumber } from "../modules/swapKitNumber";
+
+type ShareParams<T extends {}> = T & { liquidityUnits: string; poolUnits: string };
+
+type PoolParams = { runeAmount: string; assetAmount: string; runeDepth: string; assetDepth: string };
+
+/**
+ *  Ref: https://gitlab.com/thorchain/thornode/-/issues/657
+ *  share = (s * A * (2 * T^2 - 2 * T * s + s^2))/T^3
+ *  s = stakeUnits for member (after factoring in withdrawBasisPoints)
+ *  T = totalPoolUnits for pool
+ *  A = assetDepth to be withdrawn
+ *
+ *  Formula:
+ *  share = (s * A * (2 * T^2 - 2 * T * s + s^2))/T^3
+ *  (part1 * (part2 - part3 + part4)) / part5
+ */
+export function getAsymmetricRuneShare({ liquidityUnits, poolUnits, runeDepth }: ShareParams<{ runeDepth: string }>) {
+  const s = toTCSwapKitNumber(liquidityUnits);
+  const T = toTCSwapKitNumber(poolUnits);
+  const A = toTCSwapKitNumber(runeDepth);
+
+  const part1 = s.mul(A);
+  const part2 = T.mul(T).mul(2);
+  const part3 = T.mul(s).mul(2);
+  const part4 = s.mul(s);
+  const part5 = T.mul(T).mul(T);
+
+  const numerator = part1.mul(part2.sub(part3).add(part4));
+
+  return numerator.div(part5);
+}
+
+export function getAsymmetricAssetShare({
+  liquidityUnits,
+  poolUnits,
+  assetDepth,
+}: ShareParams<{ assetDepth: string }>) {
+  const s = toTCSwapKitNumber(liquidityUnits);
+  const T = toTCSwapKitNumber(poolUnits);
+  const A = toTCSwapKitNumber(assetDepth);
+
+  const part1 = s.mul(A);
+  const part2 = T.mul(T).mul(2);
+  const part3 = T.mul(s).mul(2);
+  const part4 = s.mul(s);
+  const numerator = part1.mul(part2.sub(part3).add(part4));
+  const part5 = T.mul(T).mul(T);
+
+  return numerator.div(part5);
+}
+
+export function getAsymmetricRuneWithdrawAmount({
+  percent,
+  runeDepth,
+  liquidityUnits,
+  poolUnits,
+}: ShareParams<{ percent: number; runeDepth: string }>) {
+  return getAsymmetricRuneShare({ liquidityUnits, poolUnits, runeDepth }).mul(percent);
+}
+
+export function getAsymmetricAssetWithdrawAmount({
+  percent,
+  assetDepth,
+  liquidityUnits,
+  poolUnits,
+}: ShareParams<{ percent: number; assetDepth: string }>) {
+  return getAsymmetricAssetShare({ assetDepth, liquidityUnits, poolUnits }).mul(percent);
+}
+
+function toTCSwapKitNumber(value: string) {
+  return SwapKitNumber.fromBigInt(BigInt(value), getChainConfig(Chain.THORChain).baseDecimal);
+}
+
+export function getSymmetricPoolShare({
+  liquidityUnits,
+  poolUnits,
+  runeDepth,
+  assetDepth,
+}: ShareParams<{ runeDepth: string; assetDepth: string }>) {
+  return {
+    assetAmount: toTCSwapKitNumber(assetDepth).mul(liquidityUnits).div(poolUnits),
+    runeAmount: toTCSwapKitNumber(runeDepth).mul(liquidityUnits).div(poolUnits),
+  };
+}
+
+export function getSymmetricWithdraw({
+  liquidityUnits,
+  poolUnits,
+  runeDepth,
+  assetDepth,
+  percent,
+}: ShareParams<{ runeDepth: string; assetDepth: string; percent: number }>) {
+  return Object.fromEntries(
+    Object.entries(getSymmetricPoolShare({ assetDepth, liquidityUnits, poolUnits, runeDepth })).map(([name, value]) => [
+      name,
+      value.mul(percent),
+    ]),
+  );
+}
+
+export function getEstimatedPoolShare({
+  runeDepth,
+  poolUnits,
+  assetDepth,
+  liquidityUnits,
+  runeAmount,
+  assetAmount,
+}: ShareParams<{ runeAmount: string; assetAmount: string; runeDepth: string; assetDepth: string }>) {
+  const R = new SwapKitNumber({ decimal: 8, value: runeDepth });
+  const A = new SwapKitNumber({ decimal: 8, value: assetDepth });
+  const P = new SwapKitNumber({ decimal: 8, value: poolUnits });
+  const runeAddAmount = new SwapKitNumber({ decimal: 8, value: runeAmount });
+  const assetAddAmount = new SwapKitNumber({ decimal: 8, value: assetAmount });
+
+  // liquidityUnits = P * (r*A + a*R + 2*r*a) / (r*A + a*R + 2*R*A)
+  const rA = runeAddAmount.mul(A);
+  const aR = assetAddAmount.mul(R);
+  const ra = runeAddAmount.mul(assetAddAmount);
+  const RA = R.mul(A);
+  const numerator = P.mul(rA.add(aR.add(ra.mul(2))));
+  const denominator = rA.add(aR.add(RA.mul(2)));
+  const liquidityUnitsAfterAdd = numerator.div(denominator);
+  const estimatedLiquidityUnits = toTCSwapKitNumber(liquidityUnits).add(liquidityUnitsAfterAdd);
+
+  if (liquidityUnitsAfterAdd.getBaseValue("number") === 0) {
+    return estimatedLiquidityUnits.div(P).getBaseValue("number");
+  }
+
+  // get pool units after add
+  const newPoolUnits = P.add(estimatedLiquidityUnits);
+
+  return estimatedLiquidityUnits.div(newPoolUnits).getBaseValue("number");
+}
+
+export function getLiquiditySlippage({ runeAmount, assetAmount, runeDepth, assetDepth }: PoolParams) {
+  if (runeAmount === "0" || assetAmount === "0" || runeDepth === "0" || assetDepth === "0") return 0;
+  // formula: (t * R - T * r)/ (T*r + R*T)
+  const R = toTCSwapKitNumber(runeDepth);
+  const T = toTCSwapKitNumber(assetDepth);
+  const assetAddAmount = toTCSwapKitNumber(assetAmount);
+  const runeAddAmount = toTCSwapKitNumber(runeAmount);
+
+  const numerator = assetAddAmount.mul(R).sub(T.mul(runeAddAmount));
+  const denominator = T.mul(runeAddAmount).add(R.mul(T));
+
+  // set absolute value of percent, no negative allowed
+  return Math.abs(numerator.div(denominator).getBaseValue("number"));
+}

package/src/utils/memo.ts

@@ -0,0 +1,102 @@
+import { Chain } from "@swapkit/types";
+import { match } from "ts-pattern";
+import { MemoType } from "../types/sdk";
+
+export function getMemoForLeaveAndBond({ type, address }: BondOrLeaveParams) {
+  return `${type}:${address}`;
+}
+
+export function getMemoForUnbond({ address, unbondAmount }: UnbondParams) {
+  return `${MemoType.UNBOND}:${address}:${unbondAmount}`;
+}
+
+/**
+ * Deposit
+ */
+export function getMemoForRunePoolDeposit(affiliate?: WithAffiliate<{}>) {
+  return addAffiliate(MemoType.RUNEPOOL_DEPOSIT, affiliate);
+}
+
+export function getMemoForDeposit({
+  chain,
+  symbol,
+  address,
+  ...affiliate
+}: WithAffiliate<{ chain: Chain; symbol: string; address?: string }>) {
+  const poolIdentifier = getPoolIdentifier({ chain, symbol });
+  const addressPart = address ? `:${address}:` : ":";
+
+  return addAffiliate(`${MemoType.DEPOSIT}:${poolIdentifier}${addressPart}`, affiliate);
+}
+
+/**
+ * Withdraw
+ */
+export function getMemoForWithdraw({ chain, symbol, ticker, basisPoints, targetAsset }: WithdrawParams) {
+  const shortenedSymbol = chain === "ETH" && ticker !== "ETH" ? `${ticker}-${symbol.slice(-3)}` : symbol;
+  const targetPart = targetAsset ? `:${targetAsset}` : "";
+
+  return `${MemoType.WITHDRAW}:${chain}.${shortenedSymbol}:${basisPoints}${targetPart}`;
+}
+
+export function getMemoForRunePoolWithdraw({ basisPoints, ...affiliate }: WithAffiliate<{ basisPoints: number }>) {
+  return addAffiliate(`${MemoType.RUNEPOOL_WITHDRAW}:${basisPoints}`, affiliate);
+}
+
+/**
+ * TNS
+ */
+export function getMemoForNameRegister({ name, chain, address, owner }: NameRegisterParams) {
+  const baseMemo = `${MemoType.NAME_REGISTER}:${name}:${chain}:${address}`;
+  const ownerAssignmentOrChangePart = owner ? `:${owner}` : "";
+
+  return `${baseMemo}${ownerAssignmentOrChangePart}`;
+}
+
+export function getMemoForNamePreferredAssetRegister({
+  name,
+  chain,
+  asset,
+  payout,
+  owner,
+}: PreferredAssetRegisterParams) {
+  return `${MemoType.NAME_REGISTER}:${name}:${chain}:${payout}:${owner}:${asset}`;
+}
+
+export function getMemoForTcyClaim(memoType: MemoType.CLAIM_TCY, { address }: WithAffiliate<{ address: string }>) {
+  return `${memoType}:${address}`;
+}
+
+export function getMemoForTcyStake(
+  memoType: MemoType.STAKE_TCY | MemoType.UNSTAKE_TCY,
+  { unstakeBps, ...affiliate }: WithAffiliate<{ unstakeBps?: number }>,
+) {
+  const bps = unstakeBps ? `:${unstakeBps}` : "";
+  const baseMemo = `${memoType}${bps}`;
+
+  return addAffiliate(`${baseMemo}`, affiliate);
+}
+
+/**
+ * Internal helpers
+ */
+function addAffiliate(memo: string, { affiliateAddress, affiliateBasisPoints }: WithAffiliate<{}> = {}) {
+  const affiliatedMemo = `${memo}${affiliateAddress ? `:${affiliateAddress}:${affiliateBasisPoints || 0}` : ""}`;
+
+  return affiliatedMemo.endsWith(":") ? affiliatedMemo.slice(0, -1) : affiliatedMemo;
+}
+
+function getPoolIdentifier({ chain, symbol }: { chain: Chain; symbol: string }) {
+  return match(chain)
+    .with(Chain.Bitcoin, Chain.Dogecoin, Chain.Litecoin, () => chain.slice(0, 1).toLowerCase())
+    .with(Chain.BitcoinCash, () => "c")
+    .otherwise(() => `${chain}.${symbol}`);
+}
+
+type WithAffiliate<T extends {}> = T & { affiliateAddress?: string; affiliateBasisPoints?: number };
+
+type BondOrLeaveParams = { type: MemoType.BOND | MemoType.LEAVE; address: string };
+type UnbondParams = { address: string; unbondAmount: number };
+type NameRegisterParams = { name: string; chain: string; address: string; owner?: string };
+type PreferredAssetRegisterParams = { name: string; chain: Chain; asset: string; payout: string; owner: string };
+type WithdrawParams = { chain: Chain; symbol: string; ticker: string; basisPoints: number; targetAsset?: string };

package/src/utils/others.ts

@@ -0,0 +1,62 @@
+import { Chain } from "@swapkit/types";
+import { type ErrorKeys, SwapKitError } from "../modules/swapKitError";
+
+// 10 rune for register, 1 rune per year
+// MINIMUM_REGISTRATION_FEE = 11
+export function getTHORNameCost(numberOfYears: number) {
+  if (numberOfYears < 0)
+    throw new SwapKitError({ errorKey: "helpers_invalid_number_of_years", info: { numberOfYears } });
+  return 10 + numberOfYears;
+}
+
+// 10 CACAO for register
+// 1.0512 CACAO per year
+export function getMAYANameCost(numberOfYears: number) {
+  if (numberOfYears < 0)
+    throw new SwapKitError({ errorKey: "helpers_invalid_number_of_years", info: { numberOfYears } });
+  // round to max 10 decimals
+  return Math.round((10 + numberOfYears * 1.0512) * 1e10) / 1e10;
+}
+
+export function wrapWithThrow<T>(fn: () => T, errorKey?: ErrorKeys) {
+  try {
+    return fn();
+  } catch (error) {
+    if (errorKey) {
+      throw new SwapKitError(errorKey, error);
+    }
+
+    return;
+  }
+}
+
+export function getChainIdentifier<T extends Chain>(chain: T) {
+  switch (chain) {
+    case Chain.THORChain:
+      return `${chain}.RUNE`;
+
+    case Chain.Cosmos:
+      return `${chain}.ATOM`;
+
+    case Chain.BinanceSmartChain:
+      return `${chain}`;
+
+    default:
+      return `${chain}.${chain}`;
+  }
+}
+
+const warnings = new Set();
+export function warnOnce({ condition, id, warning }: { condition: boolean; id: string; warning: string }) {
+  if (condition) {
+    if (warnings.has(id)) {
+      return;
+    }
+
+    if (process.env.NODE_ENV !== "test") {
+      console.warn(warning);
+    }
+
+    warnings.add(id);
+  }
+}

package/src/utils/validators.ts

@@ -0,0 +1,32 @@
+import type { Chain } from "@swapkit/types";
+import { SKConfig } from "../modules/swapKitConfig";
+import { SwapKitError } from "../modules/swapKitError";
+
+// Backward compatibility
+const supportedChains = ["TERRA", ...SKConfig.get("chains")];
+
+export function validateIdentifier(identifier = "") {
+  const uppercasedIdentifier = identifier.toUpperCase();
+
+  const [chain] = uppercasedIdentifier.split(".") as [Chain, string];
+  if (supportedChains.includes(chain)) return true;
+
+  const [synthChain] = uppercasedIdentifier.split("/") as [Chain, string];
+  if (supportedChains.includes(synthChain)) return true;
+
+  throw new SwapKitError({
+    errorKey: "helpers_invalid_identifier",
+    info: {
+      identifier,
+      message: `Invalid identifier: ${identifier}. Expected format: <Chain>.<Ticker> or <Chain>.<Ticker>-<ContractAddress>`,
+    },
+  });
+}
+
+export function validateTNS(name: string) {
+  if (name.length > 30) return false;
+
+  const regex = /^[a-zA-Z0-9+_-]+$/g;
+
+  return !!name.match(regex);
+}