@talismn/balances 3.0.4 → 3.0.5

package/README.md

@@ -6,111 +6,34 @@
 [![npm-version](https://img.shields.io/npm/v/@talismn/balances?style=flat-square)](https://www.npmjs.com/package/@talismn/balances)
 [![npm-downloads](https://img.shields.io/npm/dw/@talismn/balances?style=flat-square)](https://www.npmjs.com/package/@talismn/balances)
 
-**@talismn/balances** is the core of a set of packages used to subscribe to on-chain account token balances.
+**@talismn/balances** fetches and subscribes to on-chain account token balances for Polkadot SDK, Ethereum (EVM) and Solana networks.
 
-A quick rundown on each package is given below.
+It includes:
 
-### This (the core) package:
+- `BalancesProvider`: the API that wallets and dapps use to fetch and subscribe to balances (`getBalances$`)
+- `Balances` and `Balance`: classes that aggregate balances and expose `total`, `free`, `locked`, `reserved` and fiat values
+- The balance modules, one per token type, which all implement `IBalanceModule`
 
-**@talismn/balances** (this package) includes:
+Networks and tokens come from `@talismn/chaindata-provider`. RPC connections come from `@talismn/chain-connectors`.
 
-- An API which wallets / dapps can use to access balances
-- An interface for balance modules to implement
-- A shared database (powered by dexie) for balance modules to store balances in
-- Helpers (utility functions) for balance modules to use
-- Provides a plugin architecture, which is used by the balance module packages to specify their balance types
+### Balance modules
 
-### The balance modules:
+Each module is a folder in `src/modules/`:
 
-**@talismn/balances-default-modules**
+| Module | Tokens |
+| --- | --- |
+| `substrate-native` | Native tokens of Polkadot SDK chains, including locks, reserves and staking |
+| `substrate-assets` | `assets` pallet tokens |
+| `substrate-foreignassets` | `foreignAssets` pallet tokens |
+| `substrate-tokens` | ORML `tokens` pallet tokens |
+| `substrate-hydration` | Hydration multi-currency tokens (`CurrenciesApi` runtime API) |
+| `substrate-psp22` | PSP22 (ink! contract) tokens |
+| `substrate-dtao` | Bittensor subnet (dTAO) alpha stake |
+| `evm-native` | Native tokens of EVM networks |
+| `evm-erc20` | ERC20 tokens |
+| `evm-uniswapv2` | Uniswap V2 LP tokens |
+| `sol-native` | SOL |
+| `sol-spl` | SPL tokens |
+| `sol-token2022` | Token-2022 tokens |
 
-- Collates the default balance modules (which can be found below) into a single package
-
-**@talismn/substrate-native**
-
-- A balance module for substrate native tokens
-- Subscribes to the `system.account` state query balance for each token
-- Also subscribes to the crowdloans pallet balances
-- Also subscribes to the nompools pallet balances
-
-**@talismn/substrate-orml**
-
-- A proof-of-concept balance module for ORML token pallet tokens
-- Attempts to auto-detect tokens
-- **You should use @talismn/substrate-tokens instead**
-
-**@talismn/substrate-tokens**
-
-- A balance module for substrate ORML token pallet tokens
-- Supports any token which can be queried via the `tokens.accounts` state query
-- Requires configuration for each token (no auto-detection)
-- We recommend that you use this module for ORML tokens
-
-**@talismn/substrate-assets**
-
-- A balance module for substrate assets pallet tokens
-- Supports any token which can be queried via the `assets.account` state query
-- Requires configuration for each token (no auto-detection)
-
-**@talismn/substrate-equilibrium**
-
-- A balance module for substrate eqBalances pallet tokens
-- Used by [Equilibrium](https://equilibrium.io/) and [Genshiro](https://genshiro.io/)
-- Supports auto-detection
-
-**@talismn/evm-native**
-
-- A balance module for evm native tokens
-
-**@talismn/evm-erc20**
-
-- A balance module for evm erc20 tokens
-
-### The chain connectors:
-
-**@talismn/chain-connector**
-
-- A package which manages the open RPC connections to substrate chains
-- Allows developers to say "Send this query to the chain with this id", without them needing to specify which RPCs to use
-- Ensures that connections are only opened to the chains which are in use by the wallet/dapp
-- Ensures that only one connection is open per chain
-- Handles exponential backoff in the case of network failures
-- Provides an interface which can be shared between a serviceworker and frontend, which enables the two to share the pool of open connections
-- Provides an interface which mimics a polkadot-js `WsProvider`, which can be plugged into polkadot-js to make it use the shared pool of open connections
-
-**@talismn/chain-connector-evm**
-
-- A package which manages the connections to evm chains
-- Allows developers to say "Send this query to the chain with this id", without them needing to specify which RPC to use
-
-### The chaindata provider:
-
-**@talismn/chaindata-provider**
-
-- A database (powered by dexie) to store chains, evm chains and tokens in
-- An interface to interact with the database
-- Syncs with the list in the [chaindata repository](https://github.com/talismansociety/chaindata) via graphql
-- Supports custom (end-user-defined) chains and rpc overrides
-- Provides a plugin architecture, which is used by the balance module packages to specify their token types
-
-### The remaining packages:
-
-**@talismn/connection-meta**
-
-- Contains a small db which is used to optimise network performance in the wallet.
-- Two metrics are kept:
-  - chainPriorityRpc (the last known well-behaved RPC for a chain)
-  - chainBackoffInterval (the amount of time the wallet should wait before attempting to connect to a unreachable chain again)
-
-**@talismn/mutate-metadata**
-
-- A package which can splice a chain's metadata into smaller pieces
-- Enables us to make state queries across many chains at once without using all of the browser's memory
-
-**@talismn/token-rates**
-
-- Fetches and stores coingecko rates for each token in the @talismn/chaindata-provider database
-
-**@talismn/util**
-
-- Utility functions shared by the other packages, as well as the wallet and the portal
+See `BalancesModules.md` for what a module must do.

package/dist/index.d.mts

@@ -2,9 +2,9 @@ import "bignumber.js";
 import { AnyMiniMetadata, ChaindataProvider, DotNetworkId, EthNetworkId, MINIMETADATA_VERSION, NetworkId, NetworkList, SolNetworkId, Token, TokenId, TokenList, TokenOfType, TokenType } from "@talismn/chaindata-provider";
 import { NonFunctionProperties } from "@talismn/util";
 import { Observable } from "rxjs";
+import { TokenRateCurrency, TokenRates, TokenRatesList } from "@talismn/token-rates";
 import z from "zod/v4";
 import { Instruction } from "@solana/kit";
-import { TokenRateCurrency, TokenRates, TokenRatesList } from "@talismn/token-rates";
 import { Mint, TransferFee } from "@solana-program/token-2022";
 import { Enum, Enum as Enum$1, GetEnum, ResultPayload, SS58String, SizedHex } from "@polkadot-api/substrate-bindings";
 import "@polkadot-api/utils";
@@ -82,25 +82,7 @@ export type ExtraAmount<TLabel extends string> = BaseAmountWithLabel<TLabel> & {
   includeInTotal?: boolean;
 };
 //#endregion
-//#region src/types/balances.d.ts
-type FormattedAmount<GenericAmount extends AmountWithLabel<TLabel>, TLabel extends string> = Omit<GenericAmount, "amount"> & {
-  amount: BalanceFormatter;
-};
-export declare function excludeFromTransferableAmount(locks: Amount | FormattedAmount<LockedAmount<string>, string> | Array<FormattedAmount<LockedAmount<string>, string>>): bigint;
-export declare function excludeFromFeePayableLocks(locks: Amount | LockedAmount<string> | Array<LockedAmount<string>>): Array<LockedAmount<string>>;
-export declare function includeInTotalExtraAmount(extra?: FormattedAmount<ExtraAmount<string>, string> | Array<FormattedAmount<ExtraAmount<string>, string>>): bigint;
-/** A utility type used to extract the underlying `BalanceType` of a specific source from a generalised `BalanceJson` */
-export type NarrowBalanceType<S extends IBalance, P> = S extends {
-  source: P;
-} ? S : never;
-export type BalanceSource = BalanceJson["source"];
-/** TODO: Remove this in favour of a frontend-friendly `ChaindataProvider` */
-export type HydrateDb = Partial<{
-  networks: NetworkList;
-  tokens: TokenList;
-  tokenRates: TokenRatesList;
-}>;
-export type BalanceSearchQuery = Partial<NonFunctionProperties<Balance>> | ((balance: Balance) => boolean);
+//#region src/classes/Balances.d.ts
 /**
  * A collection of balances.
  */
@@ -182,7 +164,6 @@ export declare class Balances {
   get count(): number;
   /**
    * Get the summed value of balances in this collection.
-   * TODO: Sum up token amounts AND fiat amounts
    *
    * @example
    * // Get the sum of all transferable balances in usd.
@@ -190,10 +171,116 @@ export declare class Balances {
    */
   get sum(): SumBalancesFormatter;
 }
-export declare const getBalanceId: (balance: Pick<IBalance, "address" | "tokenId">) => string;
-/**
- * An individual balance.
- */
+//#endregion
+//#region src/classes/formatters.d.ts
+export declare class BalanceValueGetter {
+  #private;
+  constructor(storage: BalanceJson);
+  get(valueType: BalanceStatusTypes): AmountWithLabel<string>[];
+  add(valueType: BalanceStatusTypes, amount: Omit<AmountWithLabel<string>, "type">): void;
+}
+export declare class BalanceFormatter {
+  #private;
+  constructor(planck: string | bigint | undefined, decimals?: number | undefined, fiatRatios?: TokenRates | null);
+  toJSON: () => string;
+  get planck(): bigint;
+  get tokens(): string;
+  fiat(currency: TokenRateCurrency): number | null;
+}
+export declare class PlanckSumBalancesFormatter {
+  #private;
+  constructor(balances: Balances);
+  /**
+   * The total balance of these tokens. Includes the free and the reserved amount.
+   */
+  get total(): bigint;
+  /** The non-reserved balance of these tokens. Includes the frozen amount. Is included in the total. */
+  get free(): bigint;
+  /** The reserved balance of these tokens. Is included in the total. */
+  get reserved(): bigint;
+  /** The frozen balance of these tokens. Is included in the free amount. */
+  get locked(): bigint;
+  /** @deprecated Use balances.locked */
+  get frozen(): bigint;
+  /** The transferable balance of these tokens. Is generally the free amount - the miscFrozen amount. */
+  get transferable(): bigint;
+  /** The unavailable balance of these tokens. */
+  get unavailable(): bigint;
+  /** The feePayable balance of these tokens. Is generally the free amount - the feeFrozen amount. */
+  get feePayable(): bigint;
+}
+export declare class FiatSumBalancesFormatter {
+  #private;
+  constructor(balances: Balances, currency: TokenRateCurrency);
+  /**
+   * The total balance of these tokens. Includes the free and the reserved amount.
+   */
+  get total(): number;
+  /** The non-reserved balance of these tokens. Includes the frozen amount. Is included in the total. */
+  get free(): number;
+  /** The reserved balance of these tokens. Is included in the total. */
+  get reserved(): number;
+  /** The frozen balance of these tokens. Is included in the free amount. */
+  get locked(): number;
+  /** @deprecated Use balances.locked */
+  get frozen(): number;
+  /** The transferable balance of these tokens. Is generally the free amount - the miscFrozen amount. */
+  get transferable(): number;
+  /** The unavailable balance of these tokens. */
+  get unavailable(): number;
+  /** The feePayable balance of these tokens. Is generally the free amount - the feeFrozen amount. */
+  get feePayable(): number;
+}
+export declare class SumBalancesFormatter {
+  #private;
+  constructor(balances: Balances);
+  get planck(): PlanckSumBalancesFormatter;
+  fiat(currency: TokenRateCurrency): FiatSumBalancesFormatter;
+  change24h(currency: TokenRateCurrency): Change24hCurrencyFormatter;
+}
+export declare class Change24hCurrencyFormatter {
+  #private;
+  constructor(balances: Balances, currency: TokenRateCurrency);
+  get total(): {
+    diff: number;
+    ratio: number;
+  } | null;
+  get free(): {
+    diff: number;
+    ratio: number;
+  } | null;
+  get reserved(): {
+    diff: number;
+    ratio: number;
+  } | null;
+  get locked(): {
+    diff: number;
+    ratio: number;
+  } | null;
+  get frozen(): {
+    diff: number;
+    ratio: number;
+  } | null;
+  get transferable(): {
+    diff: number;
+    ratio: number;
+  } | null;
+  get unavailable(): {
+    diff: number;
+    ratio: number;
+  } | null;
+  get feePayable(): {
+    diff: number;
+    ratio: number;
+  } | null;
+}
+//#endregion
+//#region src/classes/FormattedAmount.d.ts
+type FormattedAmount<GenericAmount extends AmountWithLabel<TLabel>, TLabel extends string> = Omit<GenericAmount, "amount"> & {
+  amount: BalanceFormatter;
+};
+//#endregion
+//#region src/classes/Balance.d.ts
 export declare class Balance {
   #private;
   constructor(storage: BalanceJson | IBalance, hydrate?: HydrateDb);
@@ -338,10 +425,9 @@ export declare class Balance {
     coingeckoId?: string | undefined;
     noDiscovery?: boolean | undefined;
     mirrorOf?: string | undefined;
-    type: "substrate-tokens";
-    platform: "polkadot";
-    onChainId: string | number;
-    existentialDeposit: string;
+    type: "evm-erc20";
+    platform: "ethereum";
+    contractAddress: `0x${string}`;
   } | {
     id: string;
     networkId: string;
@@ -353,12 +439,8 @@ export declare class Balance {
     coingeckoId?: string | undefined;
     noDiscovery?: boolean | undefined;
     mirrorOf?: string | undefined;
-    type: "substrate-assets";
-    platform: "polkadot";
-    assetId: string;
-    isFrozen?: boolean | undefined;
-    isSufficient: boolean;
-    existentialDeposit: string;
+    type: "evm-native";
+    platform: "ethereum";
   } | {
     id: string;
     networkId: string;
@@ -370,12 +452,18 @@ export declare class Balance {
     coingeckoId?: string | undefined;
     noDiscovery?: boolean | undefined;
     mirrorOf?: string | undefined;
-    type: "substrate-hydration";
-    platform: "polkadot";
-    onChainId: number;
-    assetType: "Erc20" | "External" | "Token";
-    isSufficient: boolean;
-    existentialDeposit: string;
+    type: "evm-uniswapv2";
+    platform: "ethereum";
+    contractAddress: `0x${string}`;
+    isCustom?: boolean | undefined;
+    symbol0: string;
+    symbol1: string;
+    decimals0: number;
+    decimals1: number;
+    tokenAddress0: `0x${string}`;
+    tokenAddress1: `0x${string}`;
+    coingeckoId0?: string | undefined;
+    coingeckoId1?: string | undefined;
   } | {
     id: string;
     networkId: string;
@@ -387,9 +475,12 @@ export declare class Balance {
     coingeckoId?: string | undefined;
     noDiscovery?: boolean | undefined;
     mirrorOf?: string | undefined;
-    type: "sol-spl";
-    platform: "solana";
-    mintAddress: string;
+    type: "substrate-assets";
+    platform: "polkadot";
+    assetId: string;
+    isFrozen?: boolean | undefined;
+    isSufficient: boolean;
+    existentialDeposit: string;
   } | {
     id: string;
     networkId: string;
@@ -401,10 +492,12 @@ export declare class Balance {
     coingeckoId?: string | undefined;
     noDiscovery?: boolean | undefined;
     mirrorOf?: string | undefined;
-    type: "sol-token2022";
-    platform: "solana";
-    mintAddress: string;
-    isTransferable?: boolean | undefined;
+    type: "substrate-dtao";
+    platform: "polkadot";
+    netuid: number;
+    subnetName?: string | undefined;
+    hotkey?: string | undefined;
+    isTransferable: boolean;
   } | {
     id: string;
     networkId: string;
@@ -433,9 +526,9 @@ export declare class Balance {
     coingeckoId?: string | undefined;
     noDiscovery?: boolean | undefined;
     mirrorOf?: string | undefined;
-    type: "substrate-psp22";
+    type: "substrate-native";
     platform: "polkadot";
-    contractAddress: string;
+    existentialDeposit: string;
   } | {
     id: string;
     networkId: string;
@@ -447,9 +540,9 @@ export declare class Balance {
     coingeckoId?: string | undefined;
     noDiscovery?: boolean | undefined;
     mirrorOf?: string | undefined;
-    type: "evm-erc20";
-    platform: "ethereum";
-    contractAddress: `0x${string}`;
+    type: "substrate-psp22";
+    platform: "polkadot";
+    contractAddress: string;
   } | {
     id: string;
     networkId: string;
@@ -461,8 +554,10 @@ export declare class Balance {
     coingeckoId?: string | undefined;
     noDiscovery?: boolean | undefined;
     mirrorOf?: string | undefined;
-    type: "evm-native";
-    platform: "ethereum";
+    type: "substrate-tokens";
+    platform: "polkadot";
+    onChainId: string | number;
+    existentialDeposit: string;
   } | {
     id: string;
     networkId: string;
@@ -474,18 +569,12 @@ export declare class Balance {
     coingeckoId?: string | undefined;
     noDiscovery?: boolean | undefined;
     mirrorOf?: string | undefined;
-    type: "evm-uniswapv2";
-    platform: "ethereum";
-    contractAddress: `0x${string}`;
-    isCustom?: boolean | undefined;
-    symbol0: string;
-    symbol1: string;
-    decimals0: number;
-    decimals1: number;
-    tokenAddress0: `0x${string}`;
-    tokenAddress1: `0x${string}`;
-    coingeckoId0?: string | undefined;
-    coingeckoId1?: string | undefined;
+    type: "substrate-hydration";
+    platform: "polkadot";
+    onChainId: number;
+    assetType: "Erc20" | "External" | "Token";
+    isSufficient: boolean;
+    existentialDeposit: string;
   } | {
     id: string;
     networkId: string;
@@ -497,12 +586,8 @@ export declare class Balance {
     coingeckoId?: string | undefined;
     noDiscovery?: boolean | undefined;
     mirrorOf?: string | undefined;
-    type: "substrate-dtao";
-    platform: "polkadot";
-    netuid: number;
-    subnetName?: string | undefined;
-    hotkey?: string | undefined;
-    isTransferable: boolean;
+    type: "sol-native";
+    platform: "solana";
   } | {
     id: string;
     networkId: string;
@@ -514,9 +599,9 @@ export declare class Balance {
     coingeckoId?: string | undefined;
     noDiscovery?: boolean | undefined;
     mirrorOf?: string | undefined;
-    type: "substrate-native";
-    platform: "polkadot";
-    existentialDeposit: string;
+    type: "sol-spl";
+    platform: "solana";
+    mintAddress: string;
   } | {
     id: string;
     networkId: string;
@@ -528,8 +613,10 @@ export declare class Balance {
     coingeckoId?: string | undefined;
     noDiscovery?: boolean | undefined;
     mirrorOf?: string | undefined;
-    type: "sol-native";
+    type: "sol-token2022";
     platform: "solana";
+    mintAddress: string;
+    isTransferable?: boolean | undefined;
   } | null;
   get decimals(): number | null;
   get rates(): TokenRates | null;
@@ -581,117 +668,20 @@ export declare class Balance {
   /** The feePayable balance of this token. Is generally the free amount - the feeFrozen amount. */
   get feePayable(): BalanceFormatter;
 }
-/** raw "locked" values, straight from the IBalance JSON (see getRawTotalPlanck) */
-export declare const getRawLocks: (balance: IBalance) => AmountWithLabel<string>[];
-/**
- * Computes `new Balance(b).total.planck` without constructing a Balance (which allocates
- * several BalanceFormatters per access) — used for high-frequency zero-balance filtering.
- * MUST mirror Balance.total exactly, including the DelegatedStaking-hold/nompool rule
- * (guarded by a parity test in balance-raw-helpers.test.ts).
- */
-export declare const getRawTotalPlanck: (balance: IBalance) => bigint;
-export declare class BalanceValueGetter {
-  #private;
-  constructor(storage: BalanceJson);
-  get(valueType: BalanceStatusTypes): AmountWithLabel<string>[];
-  add(valueType: BalanceStatusTypes, amount: Omit<AmountWithLabel<string>, "type">): void;
-}
-export declare class BalanceFormatter {
-  #private;
-  constructor(planck: string | bigint | undefined, decimals?: number | undefined, fiatRatios?: TokenRates | null);
-  toJSON: () => string;
-  get planck(): bigint;
-  get tokens(): string;
-  fiat(currency: TokenRateCurrency): number | null;
-}
-export declare class PlanckSumBalancesFormatter {
-  #private;
-  constructor(balances: Balances);
-  /**
-   * The total balance of these tokens. Includes the free and the reserved amount.
-   */
-  get total(): bigint;
-  /** The non-reserved balance of these tokens. Includes the frozen amount. Is included in the total. */
-  get free(): bigint;
-  /** The reserved balance of these tokens. Is included in the total. */
-  get reserved(): bigint;
-  /** The frozen balance of these tokens. Is included in the free amount. */
-  get locked(): bigint;
-  /** @deprecated Use balances.locked */
-  get frozen(): bigint;
-  /** The transferable balance of these tokens. Is generally the free amount - the miscFrozen amount. */
-  get transferable(): bigint;
-  /** The unavailable balance of these tokens. */
-  get unavailable(): bigint;
-  /** The feePayable balance of these tokens. Is generally the free amount - the feeFrozen amount. */
-  get feePayable(): bigint;
-}
-export declare class FiatSumBalancesFormatter {
-  #private;
-  constructor(balances: Balances, currency: TokenRateCurrency);
-  /**
-   * The total balance of these tokens. Includes the free and the reserved amount.
-   */
-  get total(): number;
-  /** The non-reserved balance of these tokens. Includes the frozen amount. Is included in the total. */
-  get free(): number;
-  /** The reserved balance of these tokens. Is included in the total. */
-  get reserved(): number;
-  /** The frozen balance of these tokens. Is included in the free amount. */
-  get locked(): number;
-  /** @deprecated Use balances.locked */
-  get frozen(): number;
-  /** The transferable balance of these tokens. Is generally the free amount - the miscFrozen amount. */
-  get transferable(): number;
-  /** The unavailable balance of these tokens. */
-  get unavailable(): number;
-  /** The feePayable balance of these tokens. Is generally the free amount - the feeFrozen amount. */
-  get feePayable(): number;
-}
-export declare class SumBalancesFormatter {
-  #private;
-  constructor(balances: Balances);
-  get planck(): PlanckSumBalancesFormatter;
-  fiat(currency: TokenRateCurrency): FiatSumBalancesFormatter;
-  change24h(currency: TokenRateCurrency): Change24hCurrencyFormatter;
-}
-export declare class Change24hCurrencyFormatter {
-  #private;
-  constructor(balances: Balances, currency: TokenRateCurrency);
-  get total(): {
-    diff: number;
-    ratio: number;
-  } | null;
-  get free(): {
-    diff: number;
-    ratio: number;
-  } | null;
-  get reserved(): {
-    diff: number;
-    ratio: number;
-  } | null;
-  get locked(): {
-    diff: number;
-    ratio: number;
-  } | null;
-  get frozen(): {
-    diff: number;
-    ratio: number;
-  } | null;
-  get transferable(): {
-    diff: number;
-    ratio: number;
-  } | null;
-  get unavailable(): {
-    diff: number;
-    ratio: number;
-  } | null;
-  get feePayable(): {
-    diff: number;
-    ratio: number;
-  } | null;
-}
-export declare const filterMirrorTokens: (balance: Balance, _i: number, balances: Balance[]) => boolean;
+/** raw values of a given type, straight from the IBalance JSON (no Balance/formatter allocation) */
+//#endregion
+//#region src/types/balances.d.ts
+export type NarrowBalanceType<S extends IBalance, P> = S extends {
+  source: P;
+} ? S : never;
+export type BalanceSource = BalanceJson["source"];
+/** TODO: Remove this in favour of a frontend-friendly `ChaindataProvider` */
+export type HydrateDb = Partial<{
+  networks: NetworkList;
+  tokens: TokenList;
+  tokenRates: TokenRatesList;
+}>;
+export type BalanceSearchQuery = Partial<NonFunctionProperties<Balance>> | ((balance: Balance) => boolean);
 //#endregion
 //#region src/types/chainConnectors.d.ts
 export type ChainConnectors = {
@@ -877,6 +867,28 @@ export declare class BalancesProvider {
 }
 export declare const getSweepStaleVariant: (balance: IBalance) => IBalance;
 //#endregion
+//#region src/classes/helpers.d.ts
+export declare function excludeFromTransferableAmount(locks: Amount | FormattedAmount<LockedAmount<string>, string> | Array<FormattedAmount<LockedAmount<string>, string>>): bigint;
+export declare function excludeFromFeePayableLocks(locks: Amount | LockedAmount<string> | Array<LockedAmount<string>>): Array<LockedAmount<string>>;
+export declare function includeInTotalExtraAmount(extra?: FormattedAmount<ExtraAmount<string>, string> | Array<FormattedAmount<ExtraAmount<string>, string>>): bigint;
+/** A utility type used to extract the underlying `BalanceType` of a specific source from a generalised `BalanceJson` */
+export declare const getBalanceId: (balance: Pick<IBalance, "address" | "tokenId">) => string;
+/**
+ * An individual balance.
+ */
+export declare const filterMirrorTokens: (balance: Balance, _i: number, balances: Balance[]) => boolean;
+//#endregion
+//#region src/classes/rawBalance.d.ts
+/** raw "locked" values, straight from the IBalance JSON (see getRawTotalPlanck) */
+export declare const getRawLocks: (balance: IBalance) => AmountWithLabel<string>[];
+/**
+ * Computes `new Balance(b).total.planck` without constructing a Balance (which allocates
+ * several BalanceFormatters per access) — used for high-frequency zero-balance filtering.
+ * MUST mirror Balance.total exactly, including the DelegatedStaking-hold/nompool rule
+ * (guarded by a parity test in balance-raw-helpers.test.ts).
+ */
+export declare const getRawTotalPlanck: (balance: IBalance) => bigint;
+//#endregion
 //#region src/modules/abis/erc20BalancesAggregator.d.ts
 export declare const erc20BalancesAggregatorAbi: readonly [{
   readonly name: "balances";
@@ -23605,6 +23617,7 @@ export declare const BALANCE_MODULES: (IBalanceModule<"evm-erc20", {
 }, {
   palletId: string;
 }>)[];
+/** @deprecated unused */
 export type AnyBalanceModule = (typeof BALANCE_MODULES)[number];
 //#endregion
 export { type DTaoClaimTarget, type DTaoConvictionLockInfo, MINIMETADATA_VERSION };