refactor(networks): introduce branded network symbol

networks/README.md

@@ -13,6 +13,14 @@ Every package name must start with `network-`, followed by the network name (for
 | Suite Common | `@trezor/network-<network>-suite-common` |
 | Suite Native | `@trezor/network-<network>-suite-native` |
 
+`@trezor/network-module` contains layer-independent primitives shared by all technical layers.
+Its `NetworkSymbol` is intentionally open-ended; exhaustive symbol unions and mappings belong to
+individual network families.
+
+`@trezor/network-<network>` is the layer-independent base package for one network family. It owns
+the supported-network tuple, the exhaustive symbol union inferred from that tuple, and conversions
+between the family symbol and `NetworkSymbol`. Every technical layer may depend on this base package.
+
 Suite and Suite Native packages may depend on Suite Common. Suite Common must remain platform-independent and must not depend on Suite or Suite Native.
 
 All the 3rd party dependencies related to a network should be defined inside that network's directory. Moreover, currently they're defined only inside general, no-suffix packages, e.g. `network-cardano` (previously coins packages) and dynamically exported.
@@ -23,13 +31,15 @@ The complete structure for Bitcoin illustrates all four layers alongside optiona
 networks/
 ├── README.md
 ├── bitcoin/
+│   ├── network-bitcoin/               → @trezor/network-bitcoin (layer-independent base)
 │   ├── network-bitcoin-connect/       → @trezor/network-bitcoin-connect
 │   ├── network-bitcoin-suite/         → @trezor/network-bitcoin-suite
 │   ├── network-bitcoin-suite-common/  → @trezor/network-bitcoin-suite-common
 │   ├── network-bitcoin-suite-native/  → @trezor/network-bitcoin-suite-native
 │   ├── network-bitcoin-bip32/         → @trezor/network-bitcoin-bip32 (custom/internal)
 │   └── network-bitcoin-coinjoin/      → @trezor/network-bitcoin-coinjoin (custom/internal)
 └── <network>/
+    ├── network-<network>/
     ├── network-<network>-connect/
     ├── network-<network>-suite/
     ├── network-<network>-suite-common/
@@ -43,8 +53,10 @@ Types, runtime constants (independent of dependencies) and runtime functions sho
 what overhead is expected. Utilities using 3rd party code in runtime should always be exported in `runtime/exports.ts` and dynamically
 reexported in `runtime/index.ts` so this code is loaded on-demand, for security and performance reasons. From the top-level index file,
 `runtime/exports.ts` is directly exported instead, but importing from the package root is restricted by eslint rule in this monorepo.
+The lightweight `supported<Network>Networks`, `isSupported<Network>Network`, and
+`to<Network>NetworkSymbol` APIs belong to the `constants` entrypoint.
 
-Each general network package follows a consistent three-entrypoint layout:
+Each general network package uses the relevant entrypoints from this layout:
 
 ```
 networks/<network>/network-<network>/src/

networks/bitcoin/network-bitcoin-suite-common/package.json

@@ -14,6 +14,8 @@
     "dependencies": {
         "@noble/hashes": "^2.0.1",
         "@scure/base": "^2.0.0",
+        "@trezor/network-bitcoin": "workspace:*",
+        "@trezor/network-module": "workspace:*",
         "@trezor/network-module-suite-common-types": "workspace:*",
         "@trezor/utils": "workspace:*"
     }

networks/bitcoin/network-bitcoin-suite-common/src/BitcoinNetworkSuiteCommonNetworkModule.ts

@@ -1,19 +1,33 @@
-import type { SuiteCommonNetworkModule } from '@trezor/network-module-suite-common-types';
+import {
+    isSupportedBitcoinNetwork,
+    supportedBitcoinNetworks,
+    toBitcoinNetworkSymbol,
+} from '@trezor/network-bitcoin/constants';
+import { type NetworkSymbol, asNetworkSymbols } from '@trezor/network-module';
+import type {
+    AddressValidator,
+    SuiteCommonNetworkModule,
+} from '@trezor/network-module-suite-common-types';
 
 import { bitcoinValidator } from './addressValidator/bitcoinAddressValidator';
-import { getNetworkConfig } from './networkConfig';
 import {
-    type BitcoinNetworkSymbol,
-    getSupportedNetworks,
-    isSupportedNetwork,
-} from './supportedNetworks';
+    getAccountSyncInterval as getBitcoinAccountSyncInterval,
+    getNetworkConfig as getBitcoinNetworkConfig,
+} from './networkConfig';
+
+const supportedNetworks = asNetworkSymbols(supportedBitcoinNetworks);
 
-export type BitcoinNetworkSuiteCommonNetworkModule = SuiteCommonNetworkModule<BitcoinNetworkSymbol>;
+const addressValidator: AddressValidator<NetworkSymbol> = {
+    isAddressValid: (address, symbol) =>
+        bitcoinValidator.isAddressValid(address, toBitcoinNetworkSymbol(symbol)),
+    getAddressType: (address, symbol) =>
+        bitcoinValidator.getAddressType(address, toBitcoinNetworkSymbol(symbol)),
+};
 
-export const createBitcoinSuiteCommonNetworkModule =
-    (): BitcoinNetworkSuiteCommonNetworkModule => ({
-        addressValidator: bitcoinValidator,
-        getSupportedNetworks,
-        isSupportedNetwork,
-        getNetworkConfig,
-    });
+export const createBitcoinSuiteCommonNetworkModule = (): SuiteCommonNetworkModule => ({
+    addressValidator,
+    getSupportedNetworks: () => supportedNetworks,
+    isSupportedNetwork: isSupportedBitcoinNetwork,
+    getNetworkConfig: symbol => getBitcoinNetworkConfig(toBitcoinNetworkSymbol(symbol)),
+    getAccountSyncInterval: symbol => getBitcoinAccountSyncInterval(toBitcoinNetworkSymbol(symbol)),
+});

networks/bitcoin/network-bitcoin-suite-common/src/addressValidator/bchAddressValidator.ts

@@ -1,10 +1,9 @@
 // CashAddr address format spec:
 // https://github.com/bitcoincashorg/bitcoincash.org/blob/master/spec/cashaddr.md
 
+import type { BitcoinNetworkSymbol } from '@trezor/network-bitcoin/constants';
 import { type AddressValidator, addressType } from '@trezor/network-module-suite-common-types';
 
-import type { BitcoinNetworkSymbol } from '../supportedNetworks';
-
 type BitcoinCashNetworkSymbol = Extract<BitcoinNetworkSymbol, 'bch'>;
 
 const CASHADDR_REGEXP = /^[qQpP]{1}[0-9a-zA-Z]{41}$/;

networks/bitcoin/network-bitcoin-suite-common/src/addressValidator/bitcoinAddressValidator.test.ts

@@ -1,6 +1,6 @@
+import type { BitcoinNetworkSymbol } from '@trezor/network-bitcoin/constants';
 import { type AddressType, addressType } from '@trezor/network-module-suite-common-types';
 
-import type { BitcoinNetworkSymbol } from '../supportedNetworks';
 import { bitcoinValidator } from './bitcoinAddressValidator';
 
 type BitcoinIsAddressValidCase = {

networks/bitcoin/network-bitcoin-suite-common/src/addressValidator/bitcoinAddressValidator.ts

@@ -5,12 +5,12 @@ import { keccak_256 } from '@noble/hashes/sha3.js';
 import { bytesToHex, hexToBytes } from '@noble/hashes/utils.js';
 import { base58 } from '@scure/base';
 
+import type { BitcoinNetworkSymbol } from '@trezor/network-bitcoin/constants';
 import { type AddressValidator, addressType } from '@trezor/network-module-suite-common-types';
 import { typedObjectKeys } from '@trezor/utils';
 
 import { bchValidator } from './bchAddressValidator';
 import * as bech32 from './bech32';
-import type { BitcoinNetworkSymbol } from '../supportedNetworks';
 
 type NetworkEnvironment = 'prod' | 'testnet' | 'regtest' | 'stake';
 type HashFunction = 'sha256' | 'blake256' | 'blake256keccak256' | 'keccak256';
@@ -63,16 +63,6 @@ const BITCOIN_CURRENCIES: Record<BitcoinCurrencySymbol, BitcoinCurrency> = {
     },
 };
 
-const getCurrency = (symbol: BitcoinCurrencySymbol): BitcoinCurrency => {
-    const currency = BITCOIN_CURRENCIES[symbol];
-
-    if (!currency) {
-        throw new Error(`Unsupported bitcoin network symbol: ${symbol}`);
-    }
-
-    return currency;
-};
-
 const getNetworkEnvironment = (symbol: BitcoinNetworkSymbol): NetworkEnvironment => {
     switch (symbol) {
         case 'test':
@@ -328,7 +318,7 @@ export const getAddressType = (address: string, symbol: BitcoinNetworkSymbol) =>
         return bchValidator.getAddressType(address, symbol);
     }
 
-    const currency = getCurrency(symbol);
+    const currency = BITCOIN_CURRENCIES[symbol];
     const networkEnvironments = getNetworkEnvironments(symbol, currency);
 
     for (const networkEnvironment of networkEnvironments) {

networks/bitcoin/network-bitcoin-suite-common/src/index.ts

@@ -1,2 +1 @@
 export { createBitcoinSuiteCommonNetworkModule } from './BitcoinNetworkSuiteCommonNetworkModule';
-export type { BitcoinNetworkSuiteCommonNetworkModule } from './BitcoinNetworkSuiteCommonNetworkModule';

networks/bitcoin/network-bitcoin-suite-common/src/networkConfig.ts

@@ -1,9 +1,19 @@
+import type { BitcoinNetworkSymbol } from '@trezor/network-bitcoin/constants';
 import {
+    DEFAULT_ACCOUNT_SYNC_INTERVAL,
     type SuiteCommonNetworkConfig,
     asProtocol,
 } from '@trezor/network-module-suite-common-types';
 
-import type { BitcoinNetworkSymbol } from './supportedNetworks';
+const syncIntervalBySymbol: Readonly<Record<BitcoinNetworkSymbol, number>> = {
+    btc: DEFAULT_ACCOUNT_SYNC_INTERVAL,
+    test: DEFAULT_ACCOUNT_SYNC_INTERVAL,
+    regtest: DEFAULT_ACCOUNT_SYNC_INTERVAL,
+    ltc: DEFAULT_ACCOUNT_SYNC_INTERVAL,
+    doge: DEFAULT_ACCOUNT_SYNC_INTERVAL,
+    zec: DEFAULT_ACCOUNT_SYNC_INTERVAL,
+    bch: DEFAULT_ACCOUNT_SYNC_INTERVAL,
+};
 
 const networkConfigBySymbol: Readonly<Record<BitcoinNetworkSymbol, SuiteCommonNetworkConfig>> = {
     btc: { color: '#f29937', protocols: [asProtocol('bitcoin'), asProtocol('btc')] },
@@ -17,3 +27,6 @@ const networkConfigBySymbol: Readonly<Record<BitcoinNetworkSymbol, SuiteCommonNe
 
 export const getNetworkConfig = (symbol: BitcoinNetworkSymbol): SuiteCommonNetworkConfig =>
     networkConfigBySymbol[symbol];
+
+export const getAccountSyncInterval = (symbol: BitcoinNetworkSymbol): number =>
+    syncIntervalBySymbol[symbol];

networks/bitcoin/network-bitcoin-suite-common/tsconfig.json

@@ -2,6 +2,10 @@
     "extends": "../../../tsconfig.base.json",
     "compilerOptions": { "outDir": "libDev" },
     "references": [
+        { "path": "../network-bitcoin" },
+        {
+            "path": "../../network-module/network-module"
+        },
         {
             "path": "../../network-module/network-module-suite-common-types"
         },

networks/bitcoin/network-bitcoin-suite-common/tsconfig.lib.json

@@ -3,6 +3,10 @@
     "compilerOptions": { "outDir": "./lib" },
     "include": ["./src"],
     "references": [
+        { "path": "../network-bitcoin" },
+        {
+            "path": "../../network-module/network-module"
+        },
         {
             "path": "../../network-module/network-module-suite-common-types"
         },

networks/bitcoin/network-bitcoin/CHANGELOG.md

@@ -0,0 +1 @@
+# 10.0.0-beta.1

networks/bitcoin/network-bitcoin/jest.config.cjs

@@ -0,0 +1,11 @@
+/**
+ * Jest configuration for web packages.
+ * Keeping this file next to the package.json file instead of providing configuration
+ * with `-c ../../jest.config.base` option in package.json scripts
+ * allows us to run jest tests directly from IDEs.
+ */
+const baseConfig = require('../../../jest.config.base');
+
+module.exports = {
+    ...baseConfig,
+};

networks/bitcoin/network-bitcoin/package.json

@@ -0,0 +1,45 @@
+{
+    "name": "@trezor/network-bitcoin",
+    "version": "10.0.0-beta.1",
+    "repository": {
+        "type": "git",
+        "url": "git://github.com/trezor/trezor-suite.git"
+    },
+    "license": "MIT",
+    "sideEffects": false,
+    "main": "./src/index.ts",
+    "type": "module",
+    "exports": {
+        "./constants": "./src/constants/index.ts",
+        ".": "./src/index.ts"
+    },
+    "publishConfig": {
+        "main": "./lib/index.js",
+        "types": "./lib/index.d.ts",
+        "exports": {
+            "./constants": {
+                "types": "./lib/constants/index.d.ts",
+                "default": "./lib/constants/index.js"
+            },
+            ".": {
+                "types": "./lib/index.d.ts",
+                "default": "./lib/index.js"
+            }
+        }
+    },
+    "files": [
+        "lib/",
+        "CHANGELOG.md"
+    ],
+    "scripts": {
+        "depcheck": "yarn g:depcheck",
+        "lint:js": "yarn g:eslint '**/*.{ts,tsx,js}'",
+        "test:unit": "yarn g:jest --passWithNoTests",
+        "type-check": "yarn g:tsc --build tsconfig.json",
+        "build:lib": "yarn g:rimraf ./lib && yarn g:tsc --build tsconfig.lib.json && ../../../scripts/publish/replace-imports.sh ./lib"
+    },
+    "dependencies": {
+        "@trezor/network-module": "workspace:*",
+        "@trezor/utils": "workspace:*"
+    }
+}

networks/bitcoin/network-bitcoin/src/constants/index.ts

@@ -0,0 +1,6 @@
+export {
+    isSupportedBitcoinNetwork,
+    supportedBitcoinNetworks,
+    toBitcoinNetworkSymbol,
+} from './networkSymbol';
+export type { BitcoinNetworkSymbol } from './networkSymbol';

networks/bitcoin/network-bitcoin/src/constants/networkSymbol.ts

@@ -0,0 +1,27 @@
+import type { NetworkSymbol } from '@trezor/network-module';
+import { isArrayMember } from '@trezor/utils';
+
+export const supportedBitcoinNetworks = [
+    'btc',
+    'test',
+    'regtest',
+    'ltc',
+    'doge',
+    'zec',
+    'bch',
+] as const;
+
+export type BitcoinNetworkSymbol = (typeof supportedBitcoinNetworks)[number];
+
+export const isSupportedBitcoinNetwork = (
+    symbol: NetworkSymbol,
+): symbol is NetworkSymbol & BitcoinNetworkSymbol =>
+    isArrayMember(symbol as string, supportedBitcoinNetworks);
+
+export const toBitcoinNetworkSymbol = (symbol: NetworkSymbol): BitcoinNetworkSymbol => {
+    if (!isSupportedBitcoinNetwork(symbol)) {
+        throw new Error(`Unsupported Bitcoin network symbol: ${symbol}`);
+    }
+
+    return symbol;
+};

networks/bitcoin/network-bitcoin/src/index.ts

@@ -0,0 +1,6 @@
+export {
+    isSupportedBitcoinNetwork,
+    supportedBitcoinNetworks,
+    toBitcoinNetworkSymbol,
+} from './constants';
+export type { BitcoinNetworkSymbol } from './constants';

networks/bitcoin/network-bitcoin/tsconfig.json

@@ -0,0 +1,11 @@
+{
+    "extends": "../../../tsconfig.base.json",
+    "compilerOptions": { "outDir": "libDev" },
+    "include": [".", "**/*.json"],
+    "references": [
+        {
+            "path": "../../network-module/network-module"
+        },
+        { "path": "../../../packages/utils" }
+    ]
+}

networks/bitcoin/network-bitcoin/tsconfig.lib.json

@@ -0,0 +1,14 @@
+{
+    "extends": "../../../tsconfig.lib.json",
+    "compilerOptions": {
+        "outDir": "./lib",
+        "rootDir": "./src"
+    },
+    "include": ["./src"],
+    "references": [
+        {
+            "path": "../../network-module/network-module"
+        },
+        { "path": "../../../packages/utils" }
+    ]
+}

networks/cardano/network-cardano-suite-common/package.json

@@ -13,8 +13,9 @@
     },
     "dependencies": {
         "@scure/base": "^2.0.0",
+        "@trezor/network-cardano": "workspace:*",
+        "@trezor/network-module": "workspace:*",
         "@trezor/network-module-suite-common-types": "workspace:*",
-        "@trezor/utils": "workspace:*",
         "cbor": "^10.0.12",
         "crc": "^4.3.2"
     }