@exodus/balances 13.2.1 → 13.2.3

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [13.2.3](https://github.com/ExodusMovement/exodus-hydra/compare/@exodus/balances@13.2.2...@exodus/balances@13.2.3) (2024-07-25)
+
+### Bug Fixes
+
+- migrate definitions ([#8030](https://github.com/ExodusMovement/exodus-hydra/issues/8030)) ([d2dfde5](https://github.com/ExodusMovement/exodus-hydra/commit/d2dfde55dfa843eb52842f64b3aac3a6f9a59069))
+
+## [13.2.2](https://github.com/ExodusMovement/exodus-hydra/compare/@exodus/balances@13.2.1...@exodus/balances@13.2.2) (2024-07-18)
+
+**Note:** Version bump only for package @exodus/balances
+
 ## [13.2.1](https://github.com/ExodusMovement/exodus-hydra/compare/@exodus/balances@13.2.0...@exodus/balances@13.2.1) (2024-06-26)
 
 ### Bug Fixes

package/README.md

@@ -1,10 +1,6 @@
 # @exodus/balances
 
-This module tracks balances across assets and portfolios. It delegates to assets for any asset-specifics.
-
-## WARNING: no asset specifics!
-
-If you introduce any asset specifics like `if (assetName === 'dogicorn') balance = balance.mul(2)`, you will be fired immediately. This is a safety measure to save you from @feri42's wrath. All asset-specifics belong in `asset.api.getBalances` or other APIs inside the asset libraries.
+This Exodus SDK feature tracks the crypto-denominated balances for all enabled wallet accounts. For fiat-denominated balances, check out [@exodus/fiat-balances](../fiat-balances).
 
 ## Install
 
@@ -14,44 +10,81 @@ yarn add @exodus/balances
 
 ## Usage
 
+This feature is designed to be used together with `@exodus/headless`. See [using the sdk](../../docs/using-the-sdk.md).
+
+### Play with it
+
+1. Open the playground https://exodus-hydra.pages.dev/
+2. Run `selectors.balances.byAsset(store.getState())` in the Dev Tools Console to get balances by asset aggregated across enabled wallet accounts.
+3. Try out some other selectors from `selectors.balances`. See example usage in [tests](./redux/__tests__/selectors/).
+4. Mock an address with a balance, tick the blockchain monitor and check your balance.
+
 ```js
-import createBalances from '@exodus/balances'
-
-const balances = createBalances({
-  // see #/assets-module in exodus-browser or tests for the API
-  assetsModule,
-  // pushes data of the form `{ [walletAccount]: WalletAccount }`
-  walletAccountsAtom,
-  // @exodus/blockchain-metadata instance
-  blockchainMetadata,
-  // the types of balances supported may change. For now it's just the total balance
-  balanceFields: ['balance'],
-  // see ../modules/module/src/logger.js for API
-  logger,
+// mock your ethereum address with one that has a balance
+await exodus.debug.addressProvider.mockAddress({
+  assetName: 'ethereum',
+  walletAccount: 'exodus_0',
+  address: '0x1111111111111111111111111111111111111111',
 })
+// force tick the ethereum monitor, or wait a while
+await exodus.txLogMonitors.update({ assetName: 'ethereum', refresh: true })
+// check your balance
+selectors.balances
+  .createTotal({ assetName: 'ethereum', walletAccount: 'exodus_0' })(store.getState())
+  .toString()
+```
 
-balances.on('balances', ({ balances, changes }) => {
-  // `balances`
-  // {
-  //   [walletAccount]: {
-  //     [assetName]: {
-  //       [balanceField]: NumberUnit
-  //     }
-  //   }
-  // }
-  //
-  // `changes`
-  // {
-  //   [walletAccount]: {
-  //     [assetName]: {
-  //       [balanceField]: {
-  //         from: NumberUnit,
-  //         to: NumberUnit,
-  //       }
-  //     }
-  //   }
-  // }
-})
+### API Side
+
+See [using the sdk](../../docs/using-the-sdk.md#setup-the-api-side) for more details on how features plug into the SDK. Note that the balances feature currently doesn't provide a top level API and is meant to be used purely through selectors.
+
+If you're building a feature that requires balances, add a dependency on the `balancesAtom` as below. See also the [available balance fields](./default-config.js).
+
+```js
+const myModuleDefinition = {
+  id: 'myModule',
+  type: 'module',
+  factory: ({ balancesAtom }) => {
+    const doSomethingSpecial = async () => {
+      // {
+      //   [walletAccount]: {
+      //     [assetName]: {
+      //       // e.g. 'total', 'spendable', 'unconfirmedSent', 'unconfirmedReceived'
+      //       [balanceField]: NumberUnit, // see @exodus/currency
+      //     }
+      //   }
+      // }
+      const { balances } = await balancesAtom.get()
+      // ...
+    }
 
-balances.sync() // forces 'balances' event emission
+    return {
+      doSomethingSpecial,
+    }
+  },
+  dependencies: ['balancesAtom'],
+}
 ```
+
+### UI Side
+
+See [using the sdk](../../docs/using-the-sdk.md#events) for more details on basic UI-side setup.
+
+```js
+import { selectors } from '~/ui/flux'
+
+const MyComponent = () => {
+  const bitcoinBalance = useSelector(
+    selectors.balances.createSpendable({
+      assetName: 'bitcoin',
+      walletAccount: 'exodus_0',
+    })
+  ) // returns a NumberUnit
+}
+```
+
+## Contributing
+
+### WARNING: no asset specifics!
+
+If you introduce any asset specifics like `if (assetName === 'dogicorn') balance = balance.mul(2)`, you will be fired immediately. This is a safety measure to save you from @feri42's wrath. All asset-specifics belong in `asset.api.getBalances` or other APIs inside the asset libraries.

package/atoms/index.js

@@ -9,6 +9,7 @@ export const balancesAtomDefinition = {
   type: 'atom',
   factory: createBalancesAtom,
   dependencies: [],
+  public: true,
 }
 
 export const hasBalanceAtomDefinition = {
@@ -16,6 +17,7 @@ export const hasBalanceAtomDefinition = {
   type: 'atom',
   factory: createHasBalanceAtom,
   dependencies: ['balancesAtom', 'storage'],
+  public: true,
 }
 
 export const fundedWalletAccountsAtomDefinition = {
@@ -23,6 +25,7 @@ export const fundedWalletAccountsAtomDefinition = {
   type: 'atom',
   factory: createFundedWalletAccountsAtom,
   dependencies: ['balancesAtom', 'enabledWalletAccountsAtom'],
+  public: true,
 }
 
 export const assetNamesWithBalanceAtomDefinition = {
@@ -30,6 +33,7 @@ export const assetNamesWithBalanceAtomDefinition = {
   type: 'atom',
   factory: createAssetNamesWithBalanceAtom,
   dependencies: ['balancesAtom'],
+  public: true,
 }
 
 export const assetsWithBalanceCountAtomDefinition = {
@@ -37,4 +41,5 @@ export const assetsWithBalanceCountAtomDefinition = {
   type: 'atom',
   factory: createAssetsWithBalanceCountAtom,
   dependencies: ['assetNamesWithBalanceAtom'],
+  public: true,
 }

package/module/index.js

@@ -387,6 +387,7 @@ const balancesDefinition = {
     'accountStatesAtom',
     'assetsAtom',
   ],
+  public: true,
 }
 
 export default balancesDefinition

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@exodus/balances",
-  "version": "13.2.1",
+  "version": "13.2.3",
   "description": "Tracks crypto balances across enabled wallet accounts.",
   "author": "Exodus Movement, Inc.",
   "license": "UNLICENSED",
   "scripts": {
-    "test": "run -T jest",
+    "test": "run -T exodus-test --jest --esbuild",
     "lint": "run -T eslint . --ignore-path ../../.gitignore",
-    "lint:fix": "yarn lint --fix"
+    "lint:fix": "yarn lint --fix",
+    "format": "run -T prettier --write \"**/*.{json,md,yaml}\" --log-level warn",
+    "format:check": "run -T prettier --check \"**/*.{json,md,yaml}\" --log-level warn"
   },
   "main": "index.js",
   "files": [
@@ -30,7 +32,7 @@
     "url": "https://github.com/ExodusMovement/exodus-hydra/issues?q=is%3Aissue+is%3Aopen+label%3Abalances"
   },
   "dependencies": {
-    "@exodus/atoms": "^7.0.5",
+    "@exodus/atoms": "^8.0.0",
     "@exodus/basic-utils": "^2.5.1",
     "@exodus/core-selectors": "^1.5.0",
     "@exodus/currency": "^2.1.2",
@@ -49,17 +51,17 @@
   "devDependencies": {
     "@exodus/assets": "^8.0.94",
     "@exodus/assets-base": "^8.1.10",
-    "@exodus/assets-feature": "^5.6.0",
-    "@exodus/available-assets": "^8.3.0",
+    "@exodus/assets-feature": "^5.8.2",
+    "@exodus/available-assets": "^8.4.0",
     "@exodus/bitcoin-meta": "^1.0.1",
     "@exodus/blockchain-metadata": "^9.0.1",
     "@exodus/ethereum-meta": "^1.0.30",
-    "@exodus/fee-data-monitors": "^4.2.0",
+    "@exodus/fee-data-monitors": "^4.2.1",
     "@exodus/redux-dependency-injection": "workspace:^",
     "@exodus/storage-memory": "*",
-    "@exodus/wallet-accounts": "^16.7.1",
+    "@exodus/wallet-accounts": "^16.8.2",
     "events": "^3.3.0",
     "redux": "^4.2.1"
   },
-  "gitHead": "7c12959ab914cce84a1ba3cce64253185599eefe"
+  "gitHead": "3995391eb48639b2d60ced5224a6a8f4902a2466"
 }

package/plugins/index.js

@@ -6,6 +6,7 @@ export const balancesLifecyclePluginDefinition = {
   type: 'plugin',
   factory: createBalancesLifecyclePlugin,
   dependencies: ['balancesAtom', 'port', 'balances', 'hasBalanceAtom'],
+  public: true,
 }
 
 export const balancesAnalyticsPluginDefinition = {
@@ -13,4 +14,5 @@ export const balancesAnalyticsPluginDefinition = {
   type: 'plugin',
   factory: createBalancesAnalyticsPlugin,
   dependencies: ['analytics', 'hasBalanceAtom', 'assetsWithBalanceCountAtom'],
+  public: true,
 }

package/redux/selectors/create-balance-selectors.js

@@ -1,4 +1,4 @@
-import { memoize } from 'lodash'
+import { memoize } from 'lodash' // eslint-disable-line @exodus/restricted-imports/prefer-basic-utils -- TODO: fix next time we touch this file
 import { MY_STATE } from '@exodus/redux-dependency-injection'
 import { createSelector } from 'reselect'
 

package/redux/selectors/create-fuel-threshold.js

@@ -1,4 +1,4 @@
-import { memoize } from 'lodash'
+import { memoize } from 'lodash' // eslint-disable-line @exodus/restricted-imports/prefer-basic-utils -- TODO: fix next time we touch this file
 import { createSelector } from 'reselect'
 import { isNumberUnit } from '@exodus/currency'
 

package/redux/selectors/create-unconfirmed-balance.js

@@ -1,4 +1,4 @@
-import { memoize } from 'lodash'
+import { memoize } from 'lodash' // eslint-disable-line @exodus/restricted-imports/prefer-basic-utils -- TODO: fix next time we touch this file
 import { createSelector } from 'reselect'
 import { getUnconfirmedBalance } from './get-unconfirmed-balance'
 

package/redux/selectors/get-balance-for-field.js

@@ -1,4 +1,4 @@
-import { memoize } from 'lodash'
+import { memoize } from 'lodash' // eslint-disable-line @exodus/restricted-imports/prefer-basic-utils -- TODO: fix next time we touch this file
 import defaultConfig from '../../default-config'
 
 const { balanceFields } = defaultConfig

package/redux/selectors/get-balance-selectors.js

@@ -1,4 +1,4 @@
-import { memoize } from 'lodash'
+import { memoize } from 'lodash' // eslint-disable-line @exodus/restricted-imports/prefer-basic-utils -- TODO: fix next time we touch this file
 
 const createResultFunction = (field) => (getBalanceForField) =>
   memoize(

package/redux/selectors/get-balances.js

@@ -1,4 +1,4 @@
-import { memoize } from 'lodash'
+import { memoize } from 'lodash' // eslint-disable-line @exodus/restricted-imports/prefer-basic-utils -- TODO: fix next time we touch this file
 import { createSelector } from 'reselect'
 import { MY_STATE } from '@exodus/redux-dependency-injection'
 

package/redux/selectors/get-unconfirmed-balance.js

@@ -1,4 +1,4 @@
-import { memoize } from 'lodash'
+import { memoize } from 'lodash' // eslint-disable-line @exodus/restricted-imports/prefer-basic-utils -- TODO: fix next time we touch this file
 import { createSelector } from 'reselect'
 
 export const getUnconfirmedBalance = ({ asset, txs }) => {

package/report/index.js

@@ -40,6 +40,7 @@ const balancesReportDefinition = {
   type: 'report',
   factory: createBalancesReport,
   dependencies: ['enabledWalletAccountsAtom', 'balancesAtom'],
+  public: true,
 }
 
 export default balancesReportDefinition