@exodus/balances 13.2.1 → 13.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/CHANGELOG.md +4 -0
  2. package/README.md +111 -42
  3. package/package.json +6 -6
package/CHANGELOG.md CHANGED
@@ -3,6 +3,10 @@
3
3
  All notable changes to this project will be documented in this file.
4
4
  See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
5
5
 
6
+ ## [13.2.2](https://github.com/ExodusMovement/exodus-hydra/compare/@exodus/balances@13.2.1...@exodus/balances@13.2.2) (2024-07-18)
7
+
8
+ **Note:** Version bump only for package @exodus/balances
9
+
6
10
  ## [13.2.1](https://github.com/ExodusMovement/exodus-hydra/compare/@exodus/balances@13.2.0...@exodus/balances@13.2.1) (2024-06-26)
7
11
 
8
12
  ### Bug Fixes
package/README.md CHANGED
@@ -1,11 +1,5 @@
1
1
  # @exodus/balances
2
2
 
3
- This module tracks balances across assets and portfolios. It delegates to assets for any asset-specifics.
4
-
5
- ## WARNING: no asset specifics!
6
-
7
- 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.
8
-
9
3
  ## Install
10
4
 
11
5
  ```sh
@@ -14,44 +8,119 @@ yarn add @exodus/balances
14
8
 
15
9
  ## Usage
16
10
 
11
+ Like all Exodus SDK features, the `balances` feature consists of:
12
+
13
+ - A feature that plugs into the Exodus SDK in your logical or actual background process. This provides the `balancesAtom` to other features.
14
+ - A redux module that plugs into the Exodus SDK in the UI process. This provides selectors for getting [various balances](https://github.com/ExodusMovement/assets/blob/cd0088d03887934685c1bcbb223b55bb94705a56/docs/balances-model.md).
15
+
16
+ ### Setup
17
+
18
+ In the background process, plug `balances` into the SDK:
19
+
17
20
  ```js
18
- import createBalances from '@exodus/balances'
19
-
20
- const balances = createBalances({
21
- // see #/assets-module in exodus-browser or tests for the API
22
- assetsModule,
23
- // pushes data of the form `{ [walletAccount]: WalletAccount }`
24
- walletAccountsAtom,
25
- // @exodus/blockchain-metadata instance
26
- blockchainMetadata,
27
- // the types of balances supported may change. For now it's just the total balance
28
- balanceFields: ['balance'],
29
- // see ../modules/module/src/logger.js for API
30
- logger,
31
- })
21
+ import balances from '@exodus/balances'
22
+
23
+ // sdk is an instance of `@exodus/argo` or `@exodus/headless`
24
+ sdk.use(balances())
25
+ ```
32
26
 
33
- balances.on('balances', ({ balances, changes }) => {
34
- // `balances`
35
- // {
36
- // [walletAccount]: {
37
- // [assetName]: {
38
- // [balanceField]: NumberUnit
39
- // }
40
- // }
41
- // }
42
- //
43
- // `changes`
44
- // {
45
- // [walletAccount]: {
46
- // [assetName]: {
47
- // [balanceField]: {
48
- // from: NumberUnit,
49
- // to: NumberUnit,
50
- // }
51
- // }
52
- // }
53
- // }
27
+ In the UI process, plug the `balances` redux module into the SDK:
28
+
29
+ ```js
30
+ import { setupRedux } from '@exodus/redux-dependency-injection'
31
+ import balances from '@exodus/balances/redux'
32
+
33
+ const { selectors, createHandleEvent, reducers, initialState } = setupRedux({
34
+ dependencies: [
35
+ // other redux modules
36
+ // ...
37
+ balances,
38
+ ],
54
39
  })
55
40
 
56
- balances.sync() // forces 'balances' event emission
41
+ const handleEvent = createHandleEvent(store) // store is a redux store
57
42
  ```
43
+
44
+ Connect the background process to the UI process. In a multi-process app, you will need a transport layer:
45
+
46
+ ```js
47
+ // forward SDK events to the UI process so the relevant redux module can handle them
48
+ sdk.subscribe(({ type, payload }) => handleEvent(type, payload))
49
+ ```
50
+
51
+ ### Consuming Balances
52
+
53
+ In your feature you can now depend on the `balancesAtom`
54
+
55
+ ```js
56
+ const myModuleFactory = ({ balancesAtom }) => {
57
+ const doSomethingSpecial = async () => {
58
+ // {
59
+ // [walletAccount]: {
60
+ // [assetName]: {
61
+ // // e.g. 'total', 'spendable', 'unconfirmedSent', 'unconfirmedReceived'
62
+ // [balanceField]: NumberUnit, // see @exodus/currency
63
+ // }
64
+ // }
65
+ // }
66
+ const { balances } = await balancesAtom.get()
67
+ // ...
68
+ }
69
+
70
+ return {
71
+ doSomethingSpecial,
72
+ }
73
+ }
74
+
75
+ const myModuleDefinition = {
76
+ id: 'myModule',
77
+ type: 'module',
78
+ factory: myModuleFactory,
79
+ dependencies: ['balancesAtom'],
80
+ }
81
+ ```
82
+
83
+ ```js
84
+ // in UI
85
+ const MyComponent = () => {
86
+ const bitcoinBalance = useSelector(
87
+ selectors.balances.createSpendable({
88
+ assetName: 'bitcoin',
89
+ walletAccount: 'exodus_0',
90
+ })
91
+ ) // returns a NumberUnit
92
+ }
93
+ ```
94
+
95
+ ## Playground
96
+
97
+ Try the balances selectors in the [sdk-playground](../../apps/sdk-playground/).
98
+
99
+ In this repo root, run:
100
+
101
+ ```sh
102
+ yarn --cwd apps/sdk-playground dev
103
+ ```
104
+
105
+ Open `http://localhost:8008` in the browser and run the following in the dev tools console:
106
+
107
+ ```js
108
+ // mock your ethereum address with one that has a balance
109
+ await exodus.debug.addressProvider.mockAddress({
110
+ assetName: 'ethereum',
111
+ walletAccount: 'exodus_0',
112
+ address: '0x1111111111111111111111111111111111111111',
113
+ })
114
+ // force tick the ethereum monitor, or wait a while
115
+ await exodus.txLogMonitors.update({ assetName: 'ethereum', refresh: true })
116
+ // check your balance
117
+ selectors.balances.createTotal({ assetName: 'ethereum', walletAccount: 'exodus_0' })(
118
+ store.getState()
119
+ )
120
+ ```
121
+
122
+ ## Contributing
123
+
124
+ ### WARNING: no asset specifics!
125
+
126
+ 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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@exodus/balances",
3
- "version": "13.2.1",
3
+ "version": "13.2.2",
4
4
  "description": "Tracks crypto balances across enabled wallet accounts.",
5
5
  "author": "Exodus Movement, Inc.",
6
6
  "license": "UNLICENSED",
@@ -30,7 +30,7 @@
30
30
  "url": "https://github.com/ExodusMovement/exodus-hydra/issues?q=is%3Aissue+is%3Aopen+label%3Abalances"
31
31
  },
32
32
  "dependencies": {
33
- "@exodus/atoms": "^7.0.5",
33
+ "@exodus/atoms": "^8.0.0",
34
34
  "@exodus/basic-utils": "^2.5.1",
35
35
  "@exodus/core-selectors": "^1.5.0",
36
36
  "@exodus/currency": "^2.1.2",
@@ -49,17 +49,17 @@
49
49
  "devDependencies": {
50
50
  "@exodus/assets": "^8.0.94",
51
51
  "@exodus/assets-base": "^8.1.10",
52
- "@exodus/assets-feature": "^5.6.0",
53
- "@exodus/available-assets": "^8.3.0",
52
+ "@exodus/assets-feature": "^5.8.1",
53
+ "@exodus/available-assets": "^8.3.1",
54
54
  "@exodus/bitcoin-meta": "^1.0.1",
55
55
  "@exodus/blockchain-metadata": "^9.0.1",
56
56
  "@exodus/ethereum-meta": "^1.0.30",
57
57
  "@exodus/fee-data-monitors": "^4.2.0",
58
58
  "@exodus/redux-dependency-injection": "workspace:^",
59
59
  "@exodus/storage-memory": "*",
60
- "@exodus/wallet-accounts": "^16.7.1",
60
+ "@exodus/wallet-accounts": "^16.8.1",
61
61
  "events": "^3.3.0",
62
62
  "redux": "^4.2.1"
63
63
  },
64
- "gitHead": "7c12959ab914cce84a1ba3cce64253185599eefe"
64
+ "gitHead": "a76a22c96445bcaa05e18de0e0c323cf9dd04cba"
65
65
  }