@chain-registry/utils 1.19.17 → 1.20.0

package/README.md

@@ -12,7 +12,299 @@
    <a href="https://www.npmjs.com/package/@chain-registry/utils"><img height="20" src="https://img.shields.io/github/package-json/v/cosmology-tech/chain-registry?filename=packages%2Futils%2Fpackage.json"></a>
 </p>
 
-Utility functions for the chain-registry 
+
+This module provides utility functions for working with the data in the chain-registry, focusing on asset and chain data management within the interchain ecosystem.
+
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Chain](#chain-utilities)
+    - [Examples](#chain-examples)
+    - [Functions](#chain-functions)
+  - [Asset](#asset-utilities)
+    - [Examples](#asset-examples)
+    - [Functions](#asset-functions)
+  - [IBC](#ibc-utilities)
+    - [Examples](#ibc-examples)
+    - [Functions](#ibc-functions)
+  - [Calculation](#calculation-utilities)
+    - [Examples](#calculation-examples)
+    - [Functions](#calculation-functions)
+- [Related](#related)
+- [Credits](#credits)
+- [Disclaimer](#disclaimer)
+
+## Installation
+
+```bash
+npm install @chain-registry/utils
+```
+
+## Usage
+
+### Chain Utilities
+
+Chain Utilities enable the retrieval and management of blockchain-specific data, such as chain names, chain IDs, and gas prices.
+
+#### Chain Examples
+
+Import the functions from the package:
+
+```js
+import {
+  getGasPriceRangesFromChain,
+  getChainByChainName,
+  getChainByChainId,
+  getChainNameByChainId,
+  getChainIdByChainName,
+  getChainGasPriceRanges,
+  getChainPrettyName,
+  getChainBech32Prefix
+} from '@chain-registry/utils';
+
+// import from chain-registry or your own Chain[]
+import { chains } from 'chain-registry';
+```
+
+To retrieve a chain object by its name:
+
+```ts
+const chain = getChainByChainName(chains, 'osmosis');
+// { chain_name: 'osmosis', ... }
+```
+
+To get the chain ID by its name:
+
+```ts
+const chainId = getChainIdByChainName(chains, 'osmosis');
+// 'osmosis-1'
+```
+
+To get the pretty name of a chain:
+
+```ts
+const prettyName = getChainPrettyName(chains, 'osmosis');
+// 'Osmosis'
+```
+
+To find the gas price ranges for a chain:
+
+```ts
+const gasPriceRanges = getChainGasPriceRanges(chains, 'osmosis');
+// { low: number, average: number, high: number }
+```
+
+#### Chain Functions
+
+- `getGasPriceRangesFromChain`: Returns the gas price ranges (low, average, high) for a given chain.
+- `getChainByChainName`: Finds a chain by its name.
+- `getChainByChainId`: Retrieves a chain by its chain ID.
+- `getChainNameByChainId`: Gets the chain name associated with a given chain ID.
+- `getChainIdByChainName`: Fetches the chain ID for a specified chain name.
+- `getChainGasPriceRanges`: Provides the gas price ranges for a specified chain name.
+- `getChainPrettyName`: Returns the pretty (display) name of the chain.
+- `getChainBech32Prefix`: Gets the Bech32 prefix for a given chain.
+
+### Asset Utilities
+
+Asset Utilities facilitate access to details of blockchain assets, including denominations, symbols, and related chain data.
+
+#### Asset Examples
+
+Import the functions from the package:
+
+```js
+import {
+  getAssetByDenom,
+  getAssetBySymbol,
+  getChainLogo,
+  getChainNameByDenom,
+  getChainNameByStakingDenom,
+  getCoinGeckoIdByDenom,
+  getDenomByCoinGeckoId,
+  getDenomBySymbol,
+  getExponentByDenom,
+  getExponentBySymbol,
+  getNativeTokenByChainName,
+  getSymbolByDenom,
+  getTokenLogoByDenom,
+  getTokenNameByDenom
+} from '@chain-registry/utils';
+
+// import from chain-registry or your own AssetList[]
+import { assets } from 'chain-registry';
+
+```
+
+To find an asset by its denomination:
+
+```js
+const asset = getAssetByDenom(assets, 'uosmo', 'osmosis');
+console.log(asset?.base); // 'uosmo'
+```
+
+To get the logo URL of a chain:
+
+```js
+const logo = getChainLogo(assets, 'comdex');
+console.log(logo); // 'https://raw.githubusercontent.com/cosmos/chain-registry/master/comdex/images/cmdx.png'
+```
+
+To retrieve the CoinGecko ID by asset denomination:
+
+```js
+const coinGeckoId = getCoinGeckoIdByDenom(assets, 'uosmo');
+console.log(coinGeckoId); // 'osmosis'
+```
+
+#### Asset Functions
+
+- `getAssetByDenom`: Retrieve an asset by its denomination.
+- `getAssetBySymbol`: Find an asset by its symbol.
+- `getChainLogo`: Get the logo URL of a chain.
+- `getChainNameByDenom`: Determine the chain name given an asset's denomination.
+- `getChainNameByStakingDenom`: Find the chain name by its staking token denomination.
+- `getCoinGeckoIdByDenom`: Get the CoinGecko ID associated with an asset denomination.
+- `getDenomByCoinGeckoId`: Find the denomination for an asset given its CoinGecko ID.
+- `getSymbolByDenom`: Retrieve the symbol associated with a denomination.
+- `getDenomBySymbol`: Get the denomination of an asset by its symbol.
+- `getExponentByDenom`: Find the exponent for a denomination.
+- `getExponentBySymbol`: Get the exponent for a symbol.
+- `getNativeTokenByChainName`: Retrieve the native token for a given chain name.
+- `getTokenLogoByDenom`: Get the logo URL for a token by its denomination.
+- `getTokenNameByDenom`: Find the name of a token by its denomination.
+
+### IBC Utilities
+
+IBC Utilities provide mechanisms to derive IBC denominations and trace IBC asset paths across multiple chains, enabling the management of inter-blockchain assets.
+
+#### IBC Examples
+
+```ts
+import { 
+  getIbcAssetPath,
+  getIbcDenomByBase,
+  ibcDenom
+} from '@chain-registry/utils';
+
+// import from chain-registry or your own data
+import { assets, ibc } from 'chain-registry';
+```
+
+To get the IBC denomination for a specific asset:
+
+```ts
+const denom = getIbcDenomByBase(ibc, 'osmosis', 'akash', assets, 'uakt');
+// denom should be the IBC hashed denomination string
+```
+
+Example for AKT (Akash Token) on Osmosis:
+
+```ts
+const aktDenom = getIbcDenomByBase(ibc, 'osmosis', 'akash', assets, 'uakt');
+console.log(aktDenom); // Expected: 'ibc/1480B8FD20AD5FCAE81EA87584D269547DD4D436843C1D20F15E00EB64743EF4'
+```
+
+Example for STARS (Stargaze Token) on Osmosis:
+
+```ts
+const starsDenom = getIbcDenomByBase(ibc, 'osmosis', 'stargaze', assets, 'ustars');
+console.log(starsDenom); // Expected: 'ibc/987C17B11ABC2B20019178ACE62929FE9840202CE79498E29FE8E5CB02B7C0A4'
+```
+
+#### IBC Functions
+
+- `ibcDenom`: Generates the IBC denomination for an asset based on its transfer path.
+- `getIbcAssetPath`: Determines the path an asset takes across chains in the IBC network.
+- `getIbcDenomByBase`: Computes the IBC denomination for an asset from its base denomination.
+
+### Calculation Utilities
+
+These functions provide utilities for converting asset units and calculating their values based on market data.
+
+#### Calculation Examples
+
+```js
+import {
+  mapCoinGeckoPricesToDenoms,
+  convertBaseUnitToDollarValue,
+  convertDollarValueToBaseUnit,
+  convertBaseUnitToDisplayUnit,
+  convertDisplayUnitToBaseUnit,
+  roundDown
+} from '@chain-registry/utils';
+```
+
+This function maps prices obtained from CoinGecko to the corresponding denominations in the asset list, facilitating price-related calculations.
+
+```ts
+const priceMap = mapCoinGeckoPricesToDenoms(assets, coinGeckoPrices);
+// priceMap will now contain a mapping of denominations to their USD prices
+```
+
+
+Convert an amount in the base unit of a specified asset to its dollar value using the provided price map.
+
+```ts
+const dollarValue = convertBaseUnitToDollarValue(assets, priceMap, 'OSMO', 1000000);
+// dollarValue is the total value in USD of 1,000,000 base units of OSMO
+```
+
+Convert a dollar value into the base unit of the specified asset, based on the current price.
+
+```ts
+const baseUnit = convertDollarValueToBaseUnit(assets, priceMap, 'OSMO', 100);
+// baseUnit is the amount in base units of OSMO that equals 100 USD
+```
+
+Converts an amount from the base unit to the display unit for the specified asset.
+
+```ts
+const displayUnit = convertBaseUnitToDisplayUnit(assets, 'OSMO', 1000000);
+// displayUnit is the representation of 1,000,000 base units in display units (e.g., OSMO)
+```
+
+Converts an amount from the display unit to the base unit for the specified asset.
+
+```ts
+const baseUnit = convertDisplayUnitToBaseUnit(assets, 'OSMO', 1);
+// baseUnit is the amount in base units that corresponds to 1 display unit (e.g., 1 OSMO)
+```
+
+Rounds down a number to the nearest integer, ensuring consistent lower-bound calculations in financial operations.
+
+```ts
+const rounded = roundDown(123.4567);
+// rounded will be '123'
+```
+
+#### Calculation Functions
+
+- `mapCoinGeckoPricesToDenoms`: Maps CoinGecko price data to asset denominations.
+- `convertBaseUnitToDollarValue`: Converts an amount in the base unit of an asset to its dollar value.
+- `convertDollarValueToBaseUnit`: Converts a dollar value into the base unit of a specified asset.
+- `convertBaseUnitToDisplayUnit`: Converts an amount from the base unit to the display unit of an asset.
+- `convertDisplayUnitToBaseUnit`: Converts an amount from the display unit to the base unit of an asset.
+- `roundDown`: Rounds down a number to the nearest integer.
+
+## Related
+
+Checkout these related projects:
+
+* [@cosmology/telescope](https://github.com/cosmology-tech/telescope) Your Frontend Companion for Building with TypeScript with Cosmos SDK Modules.
+* [@cosmwasm/ts-codegen](https://github.com/CosmWasm/ts-codegen) Convert your CosmWasm smart contracts into dev-friendly TypeScript classes.
+* [chain-registry](https://github.com/cosmology-tech/chain-registry) Everything from token symbols, logos, and IBC denominations for all assets you want to support in your application.
+* [cosmos-kit](https://github.com/cosmology-tech/cosmos-kit) Experience the convenience of connecting with a variety of web3 wallets through a single, streamlined interface.
+* [create-cosmos-app](https://github.com/cosmology-tech/create-cosmos-app) Set up a modern Cosmos app by running one command.
+* [interchain-ui](https://github.com/cosmology-tech/interchain-ui) The Interchain Design System, empowering developers with a flexible, easy-to-use UI kit.
+* [starship](https://github.com/cosmology-tech/starship) Unified Testing and Development for the Interchain.
+
 ## Credits
 
 🛠 Built by Cosmology — if you like our tools, please consider delegating to [our validator ⚛️](https://cosmology.zone/validator)
+
+
+## Disclaimer
+
+AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED “AS IS”, AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.
+
+No developer or entity involved in creating this software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the code, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.

package/main/assets.js

@@ -3,15 +3,8 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.getTokenNameByDenom = exports.getTokenLogoByDenom = exports.getSymbolByDenom = exports.getNativeTokenByChainName = exports.getExponentFromAsset = exports.getExponentBySymbol = exports.getExponentByDenom = exports.getDenomBySymbol = exports.getDenomByCoinGeckoId = exports.getCoinGeckoIdByDenom = exports.getChainNameByDenom = exports.getChainLogo = exports.getAssetBySymbol = exports.getAssetByDenom = exports.customFind = void 0;
-var customFind = exports.customFind = function customFind(array, filterFn) {
-  var filteredItems = array.filter(filterFn);
-  var filterCount = filteredItems.length;
-  if (filterCount > 1) {
-    throw new Error("Ambiguity Error: ".concat(filterCount, " items found."));
-  }
-  return filteredItems[0];
-};
+exports.getTokenNameByDenom = exports.getTokenLogoByDenom = exports.getSymbolByDenom = exports.getNativeTokenByChainName = exports.getExponentFromAsset = exports.getExponentBySymbol = exports.getExponentByDenom = exports.getDenomBySymbol = exports.getDenomByCoinGeckoId = exports.getCoinGeckoIdByDenom = exports.getChainNameByStakingDenom = exports.getChainNameByDenom = exports.getChainLogo = exports.getChainByStakingDenom = exports.getAssetBySymbol = exports.getAssetByDenom = void 0;
+var _utils = require("./utils");
 var getAssetByKeyValue = function getAssetByKeyValue(assets, key, value, chainName) {
   var filteredAssets = assets.filter(function (_ref) {
     var chain_name = _ref.chain_name;
@@ -20,7 +13,7 @@ var getAssetByKeyValue = function getAssetByKeyValue(assets, key, value, chainNa
     var assets = _ref2.assets;
     return assets;
   });
-  return customFind(filteredAssets, function (asset) {
+  return (0, _utils.customFind)(filteredAssets, function (asset) {
     return asset[key] === value;
   });
 };
@@ -86,7 +79,7 @@ var getExponentBySymbol = exports.getExponentBySymbol = function getExponentBySy
   return asset ? getExponentFromAsset(asset) : undefined;
 };
 var getNativeTokenByChainName = exports.getNativeTokenByChainName = function getNativeTokenByChainName(assets, chainName) {
-  var assetList = customFind(assets, function (assetList) {
+  var assetList = (0, _utils.customFind)(assets, function (assetList) {
     return assetList.chain_name === chainName && !assetList.assets[0].base.startsWith('ibc/');
   });
   return assetList === null || assetList === void 0 ? void 0 : assetList.assets[0];
@@ -113,9 +106,21 @@ var getChainNameByDenom = exports.getChainNameByDenom = function getChainNameByD
       return t.type === 'ibc';
     })) === null || _asset$traces$find === void 0 ? void 0 : (_asset$traces$find$co = _asset$traces$find.counterparty) === null || _asset$traces$find$co === void 0 ? void 0 : _asset$traces$find$co.chain_name;
   }
-  return (_customFind = customFind(assets, function (assetList) {
+  return (_customFind = (0, _utils.customFind)(assets, function (assetList) {
     return assetList.assets.some(function (asset) {
       return asset.base === denom;
     });
   })) === null || _customFind === void 0 ? void 0 : _customFind.chain_name;
+};
+var getChainByStakingDenom = exports.getChainByStakingDenom = function getChainByStakingDenom(chains, denom) {
+  return (0, _utils.customFind)(chains, function (chain) {
+    var _chain$staking;
+    return !!((_chain$staking = chain.staking) !== null && _chain$staking !== void 0 && _chain$staking.staking_tokens.find(function (token) {
+      return token.denom === denom;
+    }));
+  });
+};
+var getChainNameByStakingDenom = exports.getChainNameByStakingDenom = function getChainNameByStakingDenom(chains, denom) {
+  var _getChainByStakingDen;
+  return (_getChainByStakingDen = getChainByStakingDenom(chains, denom)) === null || _getChainByStakingDen === void 0 ? void 0 : _getChainByStakingDen.chain_name;
 };

package/main/chains.js

@@ -4,7 +4,7 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.getGasPriceRangesFromChain = exports.getChainPrettyName = exports.getChainNameByChainId = exports.getChainIdByChainName = exports.getChainGasPriceRanges = exports.getChainByChainName = exports.getChainByChainId = exports.getChainBech32Prefix = void 0;
-var _assets = require("./assets");
+var _utils = require("./utils");
 var getGasPriceRangesFromChain = exports.getGasPriceRangesFromChain = function getGasPriceRangesFromChain(chain) {
   var _chain$fees, _chain$fees$fee_token, _feeToken$low_gas_pri, _feeToken$average_gas, _feeToken$high_gas_pr;
   var feeToken = (_chain$fees = chain.fees) === null || _chain$fees === void 0 ? void 0 : (_chain$fees$fee_token = _chain$fees.fee_tokens) === null || _chain$fees$fee_token === void 0 ? void 0 : _chain$fees$fee_token[0];
@@ -15,12 +15,12 @@ var getGasPriceRangesFromChain = exports.getGasPriceRangesFromChain = function g
   };
 };
 var getChainByChainName = exports.getChainByChainName = function getChainByChainName(chains, chainName) {
-  return (0, _assets.customFind)(chains, function (chain) {
+  return (0, _utils.customFind)(chains, function (chain) {
     return chain.chain_name === chainName;
   });
 };
 var getChainByChainId = exports.getChainByChainId = function getChainByChainId(chains, chainId) {
-  return (0, _assets.customFind)(chains, function (chain) {
+  return (0, _utils.customFind)(chains, function (chain) {
     return chain.chain_id === chainId;
   });
 };

package/main/utils.js

@@ -0,0 +1,14 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.customFind = void 0;
+var customFind = exports.customFind = function customFind(array, filterFn) {
+  var filteredItems = array.filter(filterFn);
+  var filterCount = filteredItems.length;
+  if (filterCount > 1) {
+    throw new Error("Ambiguity Error: ".concat(filterCount, " items found."));
+  }
+  return filteredItems[0];
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chain-registry/utils",
-  "version": "1.19.17",
+  "version": "1.20.0",
   "description": "Chain Registry Utils",
   "author": "Dan Lynch <pyramation@gmail.com>",
   "homepage": "https://github.com/cosmology-tech/chain-registry",
@@ -40,6 +40,21 @@
   "bugs": {
     "url": "https://github.com/cosmology-tech/chain-registry/issues"
   },
+  "jest": {
+    "preset": "ts-jest",
+    "testEnvironment": "node",
+    "transform": {
+      "^.+\\.ts?$": "ts-jest"
+    },
+    "transformIgnorePatterns": [
+      "<rootDir>/node_modules/"
+    ],
+    "testPathIgnorePatterns": [
+      "main/",
+      "module/",
+      "types/"
+    ]
+  },
   "devDependencies": {
     "@babel/cli": "7.21.0",
     "@babel/core": "7.21.4",
@@ -72,9 +87,9 @@
   },
   "dependencies": {
     "@babel/runtime": "^7.21.0",
-    "@chain-registry/types": "^0.18.18",
+    "@chain-registry/types": "^0.19.0",
     "bignumber.js": "9.1.1",
     "sha.js": "^2.4.11"
   },
-  "gitHead": "d983cda0c1b7ab81b3336a539b70042f13df317f"
+  "gitHead": "a1c406b27dc7a91527a5239b565c5a528d3bb03b"
 }

package/types/assets.d.ts

@@ -1,7 +1,6 @@
-import { Asset, AssetDenomUnit, AssetList } from '@chain-registry/types';
+import { Asset, AssetDenomUnit, AssetList, Chain } from '@chain-registry/types';
 export type Denom = AssetDenomUnit['denom'];
 export type Exponent = AssetDenomUnit['exponent'];
-export declare const customFind: <T>(array: T[], filterFn: (item: T) => boolean) => T;
 export declare const getAssetByDenom: (assets: AssetList[], denom: Denom, chainName?: string) => Asset | undefined;
 export declare const getAssetBySymbol: (assets: AssetList[], symbol: string, chainName?: string) => Asset | undefined;
 export declare const getDenomByCoinGeckoId: (assets: AssetList[], coinGeckoId: string, chainName?: string) => Denom | undefined;
@@ -22,4 +21,6 @@ export declare const getTokenLogoByDenom: (assets: AssetList[], denom: Denom, ch
 export declare const getChainLogo: (assets: AssetList[], chainName: string) => string | undefined;
 export declare const getTokenNameByDenom: (assets: AssetList[], denom: Denom, chainName?: string) => string | undefined;
 export declare const getChainNameByDenom: (assets: AssetList[], denom: Denom) => string | undefined;
+export declare const getChainByStakingDenom: (chains: Chain[], denom: Denom) => Chain | undefined;
+export declare const getChainNameByStakingDenom: (chains: Chain[], denom: Denom) => string | undefined;
 export {};

package/types/ibc.d.ts

@@ -7,40 +7,55 @@ export declare const getIbcInfo: (ibc: IBCInfo[], chain: string, counterparty: s
 export declare const getTransferChannel: (info: IBCInfo) => {
     chain_1: {
         channel_id: string;
+        client_id?: string;
         port_id: string;
+        connection_id?: string;
     };
     chain_2: {
         channel_id: string;
+        client_id?: string;
         port_id: string;
+        connection_id?: string;
     };
     ordering: string;
     version: string;
+    fee_version?: string;
     tags?: object;
 };
 export declare const getNonTransferChannel: (info: IBCInfo) => {
     chain_1: {
         channel_id: string;
+        client_id?: string;
         port_id: string;
+        connection_id?: string;
     };
     chain_2: {
         channel_id: string;
+        client_id?: string;
         port_id: string;
+        connection_id?: string;
     };
     ordering: string;
     version: string;
+    fee_version?: string;
     tags?: object;
 };
 export declare const getWasmChannel: (info: IBCInfo) => {
     chain_1: {
         channel_id: string;
+        client_id?: string;
         port_id: string;
+        connection_id?: string;
     };
     chain_2: {
         channel_id: string;
+        client_id?: string;
         port_id: string;
+        connection_id?: string;
     };
     ordering: string;
     version: string;
+    fee_version?: string;
     tags?: object;
 };
 export declare const getIbcAssetPath: (ibc: IBCInfo[], chain: string, counterparty: string, assets: AssetList[], base: string) => any;

package/types/index.d.ts

@@ -1,4 +1,4 @@
-export * from './ibc';
+export * from './assets';
 export * from './calc';
 export * from './chains';
-export * from './assets';
+export * from './ibc';

package/types/utils.d.ts

@@ -0,0 +1 @@
+export declare const customFind: <T>(array: T[], filterFn: (item: T) => boolean) => T;