trac-msb 0.2.4 → 0.2.5

package/.dockerignore

@@ -0,0 +1,16 @@
+node_modules
+npm-debug.log*
+.git
+.gitignore
+.github
+.idea
+.vscode
+coverage
+docs
+migration
+dockerfile
+proto
+stores
+tests
+whitelist
+docker-compose.yml

package/.github/workflows/acceptance-tests.yml

@@ -2,6 +2,11 @@ name: MSB-Acceptance-Tests
 
 on:
   workflow_dispatch:
+  # TODO: re-enable when runners handle acceptance reliably outside local
+  # workflow_run:
+  #   workflows: ["MSB-Unit-Tests"]
+  #   types:
+  #     - completed
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
@@ -11,6 +16,8 @@ jobs:
   integration-tests:
     name: Acceptance Tests
     runs-on: ${{ matrix.os }}
+    # if: ${{ github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success' }}
+    if: ${{ github.event_name == 'workflow_dispatch' }}
     strategy:
       matrix:
         node-version: [lts/*]

package/.github/workflows/publish.yml

@@ -0,0 +1,40 @@
+name: Publish trac-msb to npm on release
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  publish-npm:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+
+      - name: Use Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Set package.json version from tag
+        run: |
+          TAG="${GITHUB_REF#refs/tags/}"
+          VERSION="${TAG#v}"
+          echo "Version from tag: $VERSION"
+          npm version "$VERSION" --no-git-tag-version
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run unit tests
+        run: npm run test:unit:all
+
+      - name: Publish to npm
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_MSB_PUBLISH_TOKEN }}
+        run: npm publish

package/.github/workflows/{CI.yml → unit-tests.yml}

@@ -1,4 +1,4 @@
-name: MSB-CI
+name: MSB-Unit-Tests
 
 on:
   push:

package/README.md

@@ -2,77 +2,202 @@
 
 A peer-to-peer crypto validator network to verify and append transactions.
 
-Release 1 (R1) must be used alongside Trac Network R1 releases to maintain contract consistency.
+Always follow the guidance in the [Security Policy](SECURITY.md) for release compatibility, upgrade steps, and required follow-up actions.
 
-The MSB is utilizing the [Pear Runtime and Holepunch](https://pears.com/).
+The MSB leverages the [Pear Runtime and Holepunch](https://pears.com/).
+
+## Prerequisites
+
+Node.js is required to run the application. Before installing Node.js, refer to the official [Node.js documentation](https://nodejs.org) for the latest recommended version and installation instructions. For this project, Node.js v24.11.0 (LTS) and npm 11.6.1 or newer are compatible.
+
+The Pear Runtime CLI is required to run the application. Before installing Pear, refer to the official [Pear documentation](https://docs.pears.com/guides/getting-started) for the latest recommended version and installation instructions. For this project, the latest Pear CLI is compatible.
+
+Install Pear globally:
+
+```sh
+npm install -g pear
+which pear
+```
+
+Docker is optional and only needed for running the containerized RPC node. Before installing Docker, refer to the official [Docker documentation](https://www.docker.com) for the latest recommended version and installation instructions. For running the containerized RPC node, the latest Docker is recommended. Tested with Docker version 28.3.2, build 578ccf6.
 
 ## Install
 
 ```shell
-git clone -b msb-r1 --single-branch git@github.com:Trac-Systems/main_settlement_bus.git
+git clone -b main --single-branch git@github.com:Trac-Systems/main_settlement_bus.git
+cd main_settlement_bus
+npm install
+```
+
+## Post-install checklist
+
+Before running tests, install bare globally:
+
+```sh
+npm install -g bare
 ```
 
+- ✅ `npm run test:unit:all` – confirms the codebase builds and runs under both supported runtimes.
+- 📋 `npm run test:acceptance` – optional but recommended before upgrades. This suite spins up in-process nodes and may take a few minutes.
+- 🌐 RPC smoke test – start `MSB_STORE=smoke-store MSB_HOST=127.0.0.1 MSB_PORT=5000 npm run env-prod-rpc` in one terminal, then execute `curl -s http://127.0.0.1:5000/v1/fee` from another terminal to verify `/v1` routes respond. Stop the node with `Ctrl+C` once finished.
+
 ## Usage
 
-While the MSB supports native node-js, it is encouraged to use Pear:
+Runtime entry points cover CLI-driven runs (`prod`, `prod-rpc`) and `.env`-aware runs (`env-prod`, `env-prod-rpc`). Each section below lists the accepted configuration inputs.
+
+### Interactive regular node
+
+#### Regular node with .env file
+
+This variant reads configuration from `.env`:
+
+```
+# .env
+MSB_STORE=<store_name>
+```
+
+then
 
-```js
-cd main_settlement_bus
-npm install -g pear
-npm install
 ```
+npm run env-prod
+```
+
+The script sources `.env` before invoking program and falls back to `node-store` when `MSB_STORE` is not defined.
 
-You can run the node in two modes:
-1. Regular node (validator/indexer):
-```js
-pear run . store1
+#### Inline environment variables
+
+```sh
+MSB_STORE=<store_name> npm run env-prod
 ```
 
-2. Admin node (access to administrative commands):
-```js
-pear run . admin
+This run persists data under `./stores/${MSB_STORE}` (defaults to `node-store`) and is intended for inline or CLI-supplied configuration.
+
+#### CLI flags
+
+```sh
+npm run prod --store=<store_name>
 ```
 
-The admin mode provides access to additional commands such as `/add_admin`, `/add_whitelist`, `/balance_migration`, `/disable_initialization`, `/add_indexer`, `/remove_indexer`, and `/ban_writer`. These commands are only visible and available when running in admin mode.
+### RPC-enabled node
+
+#### RPC with .env file
+
+```
+# .env
+MSB_STORE=<store_name>
+MSB_HOST=127.0.0.1
+MSB_PORT=5000
+```
+
+```
+npm run env-prod-rpc
+```
+
+This entry point sources `.env` automatically and defaults to `rpc-node-store`, `127.0.0.1`, and `5000` when variables are not present.
+
+#### Inline environment variables
+
+```sh
+MSB_STORE=<store_name> MSB_HOST=<host> MSB_PORT=<port> npm run env-prod-rpc
+```
+
+Override any combination of `MSB_STORE`, `MSB_HOST`, or `MSB_PORT`. Data is persisted under `./stores/${MSB_STORE}` (default `rpc-node-store` for this script).
+
+#### CLI flags
+
+```sh
+npm run prod-rpc --store=<store_name> --host=<host> --port=<port>
+```
+
+## Docker usage
+
+You can run the RPC node in a containerized environment using the provided `docker-compose.yml` file. The `msb-rpc` service is already wired up. You usually only need to tweak these variables:
+
+- `MSB_STORE`: name of the store directory under `./stores`.
+- `MSB_HOST`: host interface to bind (defaults to `127.0.0.1` to avoid exposing everything).
+- `MSB_PORT`: port the RPC server listens on **inside** the container (defaults to `5000`).
+- `MSB_PUBLISH_PORT`: host port to expose (defaults to `MSB_PORT`, so set it only when the host port should differ).
+
+Leave `MSB_PORT=5000` if you just want to publish the default RPC port and only bump `MSB_PUBLISH_PORT` when the host side must change. Set both to the same value if you want the RPC server itself to listen on another port.
+
+Example (keep container port 5000, expose host port 6000):
+
+```sh
+MSB_STORE=rpc-node-store \
+MSB_HOST=127.0.0.1 \
+MSB_PORT=5000 \
+MSB_PUBLISH_PORT=6000 \
+docker compose up -d msb-rpc
+```
+
+### Running `msb-rpc` with Docker Compose
+
+Any of the following launch methods can be applied:
+
+1. **Using a `.env` file** – populate `.env`, then start the service:
+
+   ```sh
+   docker compose up -d msb-rpc
+   ```
+
+   or
+
+   ```sh
+   docker compose --env-file .env up -d msb-rpc
+   ```
+
+   Add any of the variables listed above to `.env`. When the host port needs to differ from the container port, set `MSB_PUBLISH_PORT` without touching `MSB_PORT`.
+
+   Example `.env` (publishes host port 1337, keeps the container on 5000):
+
+   ```dotenv
+   MSB_STORE=rpc-node-store
+   MSB_HOST=127.0.0.1
+   MSB_PORT=5000
+   MSB_PUBLISH_PORT=1337
+   ```
+
+2. **Passing variables inline** – use this method when environment variables should be provided directly in the command line, without modifying the `.env` file:
+
+   ```sh
+   MSB_STORE=<store_name> MSB_HOST=<host> MSB_PORT=<container_port> MSB_PUBLISH_PORT=<host_port> docker compose up -d msb-rpc
+   ```
+
+   Skip `MSB_PORT` when you just want to keep the container on `5000` and expose a different host port.
+
+3. **Reusing an existing store directory** – mount the path that already holds your store and pin the host binding you need:
 
-**Deploy Bootstrap (admin):**
+   ```sh
+   docker compose run -d --name msb-rpc \
+      -e MSB_STORE=<store_name> \
+      -e MSB_HOST=<host> \
+      -e MSB_PORT=<container_port> \
+      -e MSB_PUBLISH_PORT=<host_port> \
+      -p <host_address>:<host_port>:<container_port> \
+      -v /absolute/path/to/your/store_directory:/msb/stores \
+      msb-rpc
+   ```
 
-- Choose option 1)
-- Copy and backup the seedphrase
-- Copy the "MSB Writer" address
-- With a text editor, open the file msb.mjs in document root
-- Replace the bootstrap address with the copied writer address
-- Choose a channel name (exactly 32 characters)
-- Run again: pear run . store1
-- After the options appear, type /add_admin and hit enter
-- Your instance is now the Bootstrap and admin peer, required to control validators
-- Keep your bootstrap node running
-- Strongly recommended: add a couple of nodes as writers
+   Adjust `/absolute/path/to/your/store_directory` to the directory that already contains the persisted store. Once the container exists, bring it back with `docker compose start msb-rpc`. If the container should stay on `5000`, omit `-e MSB_PORT=<container_port>` and just set `MSB_PUBLISH_PORT` plus the matching `-p` flag.
 
-**Running indexers (admin)**
+   Example with specific values:
 
-- Install on different machines than the Bootstrap's (ideally different data centers)
-- Follow the "Running as validator" and then "Adding validators" procedures below
-- Copy the MSB Writer address from your writer screen
-- In your Bootstrap screen, add activate the new writers:
-- /add_indexer <MSB Writer address (not the MSB address!)>
-- You should see a success confirmation
-- Usually 2 indexers on different locations are enough, we recommend 2 to max. 4 in addition to the Bootstrap
+   ```sh
+   docker compose run -d --name msb-rpc \
+       -e MSB_STORE=rpc-node-store \
+       -e MSB_HOST=127.0.0.1 \
+       -e MSB_PORT=5000 \
+       -e MSB_PUBLISH_PORT=6000 \
+       -p 127.0.0.1:6000:5000 \
+       -v /absolute/path/to/your/store_directory:/msb/stores \
+       msb-rpc
+   ```
 
-**Running as validator (first run):**
+Stop the service with `docker compose stop msb-rpc`, remove the stack entirely with `docker compose down` when you are finished.
 
-- Choose option 1)
-- Copy and backup the seedphrase
-- Copy the "MSB Address" after the screen fully loaded
-- Hand your "MSB Address" over to the MSB admin for whitelisting
-- Wait for the admin to announce the whitelist event
-- In the screen type /add_writer
-- After a few seconds you should see your validator being added as a writer
+> Note: The RPC instance must synchronize with the network after startup, so full readiness may take some time.
 
-**Adding validators (admin):**
+## Troubleshooting
 
-- Open the file /Whitelist/pubkeys.csv with a text editor
-- Add as man Trac Network addresses as you wish
-- In the MSB screen, enter /add_whitelist
-- Wait for the listto  be fully processed
-- Inform your validator community being whitelisted
+- **Dependency install failures** – confirm you are on Node.js v24.11.0 (LTS) and npm ≥ 11.6.1. If packages still fail to build, clear artifacts (`rm -rf node_modules package-lock.json && npm install`) and rerun `npm run test:unit:all`.
+- **Unit tests fail only in one runtime** – run the targeted commands (`npm run test:unit:node` or `npm run test:unit:bare`) to isolate regressions, then inspect `tests/unit/unit.test.js` for the failing cases.

package/docker-compose.yml

@@ -0,0 +1,16 @@
+services:
+  msb-rpc:
+    build:
+      context: .
+      dockerfile: dockerfile
+    container_name: msb-rpc
+    restart: always
+    environment:
+      MSB_STORE: ${MSB_STORE:-rpc-node-store}
+      MSB_HOST: ${MSB_HOST:-127.0.0.1}
+      MSB_PORT: ${MSB_PORT:-5000}
+    volumes:
+      - ./stores:/msb/stores
+    ports:
+      - "${MSB_HOST:-127.0.0.1}:${MSB_PUBLISH_PORT:-5000}:${MSB_PORT:-5000}"
+    read_only: true

package/dockerfile

@@ -0,0 +1,41 @@
+FROM node:22-bookworm-slim
+
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends \
+    libatomic1 \
+    libgcc-s1 \
+    libstdc++6 \
+  && rm -rf /var/lib/apt/lists/*
+
+RUN groupadd --system ops \
+  && useradd --system --gid ops --home /home/ops --shell /usr/sbin/nologin ops \
+  && mkdir -p /home/ops \
+  && chown ops:ops /home/ops \
+  && mkdir -p /msb/stores \
+  && chown -R node:ops /msb
+
+WORKDIR /msb
+
+USER node
+
+COPY package*.json ./
+RUN npm ci --omit=dev
+COPY . .
+
+USER root
+RUN chown -R node:ops /msb \
+  && chmod -R 0555 /msb \
+  && chown -R node:node /msb/stores \
+  && chmod 0700 /msb/stores
+
+USER node
+
+ENV MSB_STORE=node-store \
+    MSB_HOST=0.0.0.0 \
+    MSB_PORT=5000
+
+VOLUME ["/msb/stores"]
+EXPOSE 5000
+
+ENTRYPOINT ["npm", "run"]
+CMD ["env-prod-rpc-docker"]

package/docs/fee_distribution.md

@@ -0,0 +1,89 @@
+# Fee distribution (state.js)
+
+## Constants
+- `FEE` = 0.03 $TNK base fee.
+- Predefined splits: `PERCENT_75`, `PERCENT_50`, `PERCENT_25`.
+
+## Operations (excluding TRANSFER and TX)
+| Operation | Who pays / amount | When charged | Validator | Remainder |
+| --- | --- | --- | --- | --- |
+| AddAdmin | Admin, `0` | One-time during initialization | 0% | n/a (free) |
+| BalanceInitialization | Admin (sender), `0` | While initialization flag is enabled | 0% | n/a (free) |
+| AppendWhitelist | Admin, `FEE` | Only if initialization flag is disabled | 0% | 100% burned (deducted from admin) |
+| AddWriter | Writer candidate, `FEE` | Always charged | 75% | 25% burned |
+| RemoveWriter | Writer being removed, `FEE` | Always charged | 75% | 25% burned |
+| AdminRecovery | Admin, `FEE` | Always charged | 75% | 25% burned |
+| AddIndexer | Admin, `FEE` | Always charged | 0% | 100% burned |
+| RemoveIndexer | Admin, `FEE` | Always charged | 0% | 100% burned |
+| BanValidator | Admin, `FEE` | Always charged | 0% | 100% burned |
+| BootstrapDeployment | Deployment initiator, `FEE` | Always charged | 75% | 25% burned |
+| Transfer | Requester, `FEE` | Always charged | 75% | 25% burned |
+| TX | Requester, `FEE` | Always charged | depends on subnet owner (see TX cases) | depends on subnet owner (see TX cases) |
+
+### Operation details
+- **AddAdmin**
+  - Payer: admin (network creator), amount: free.
+  - Effect: admin receives initial balance `1000 $TNK` and initial staked balance `0.3 $TNK`; admin is set as indexer+validator+whitelisted and admin entry is created. Runs exactly once during bootstrap.
+- **AddWriter**
+  - Payer: writer candidate, amount: `FEE`.
+  - Split: validator 75%, burned 25%.
+  - Effect: role set to writer, staking updated, key registered.
+- **RemoveWriter**
+  - Payer: writer being removed, amount: `FEE`.
+  - Split: validator 75%, burned 25%.
+  - Effect: role set to whitelisted, stake released, writer key unregistered.
+- **AdminRecovery**
+  - Payer: admin rotating writer key, amount: `FEE`.
+  - Split: validator 75%, burned 25%.
+  - Effect: admin writer key swapped, indexer entry updated to the new key.
+- **BootstrapDeployment**
+  - Payer: deployment initiator, amount: `FEE`.
+  - Split: validator 75%, burned 25%.
+  - Effect: deployment entry stored for the bootstrap.
+
+## Transfer (OperationType.TRANSFER)
+- Payer: requester (sender).
+- Fee: `FEE` (always charged, in self-transfer only the fee is deducted).
+- Basics:
+  - Amount deducted from sender: `transferAmount + FEE`. In self-transfer only the fee is deducted.
+  - If the sender lacks full funds for the deduction, the operation is ignored (state unchanged).
+- Fee split: validator 75%, burned 25%.
+- Transfer amount to recipient:
+  - Recipient is not a validator: recipient gets `transferAmount` (can be 0). A new recipient is initialized as READER with that balance.
+  - Recipient is the validator: validator gets `transferAmount` plus its fee share (75% of `FEE`).
+  - Self-transfer: recipient equals sender. Recipient balance is unchanged. Fee still goes 75% to validator, 25% burned.
+
+## Subnetwork TX (OperationType.TX)
+- Payer: requester.
+- Fee: `FEE`.
+- Fee split depends on who deployed the subnet (`bootstrapDeployer`):
+  1. `bootstrapDeployer = requester`, validator is different:
+     - Validator: 50%
+     - Bootstrap deployer: 0% (no discount for owning the subnet)
+     - Burned: 50%
+  2. `bootstrapDeployer = validator`, requester is different:
+     - Validator (and deployer): 75% (50% as validator + 25% as deployer)
+     - Burned: 25%
+     - Requester: 0%
+  3. `bootstrapDeployer` is neither requester nor validator:
+     - Validator: 50%
+     - Bootstrap deployer: 25%
+     - Burned: 25%
+     - Requester: 0%
+- The fee is deducted from the requester before distribution. Others receive only the shares above.
+
+## Zero-fee operations
+- `ADD_ADMIN` (one-time bootstrap, assigns `1000 $TNK` liquid + `0.3 $TNK` staked to admin).
+- `BALANCE_INITIALIZATION` (sender -> recipient top-up) is free while initialization is enabled.
+- `DISABLE_INITIALIZATION` is free, can be used exactly once to turn off balance initialization.
+- AppendWhitelist before initialization is disabled is free (fee appears only after the flag is turned off).
+
+## Validator penalties
+- For a batch with invalid operations or an oversized batch: `penalty = FEE * invalidOperations`.
+- The penalty is taken from staked balance, not distributed, and the validator is downgraded to whitelisted. Remaining stake after the penalty returns to the normal balance, so part of the penalty is effectively burned.
+- Each failed operation in a batch (validation errors, unmet conditions, invalid payload) increases the invalid counter and triggers at least one `FEE` worth of penalty.
+
+## Note on the `bs` field in TX
+- `bs` identifies the subnet bootstrap, mapped in MSB to the subnet creator address.
+- A TX is valid only if `bs` points to a registered bootstrap.
+- The subnet owner (address tied to `bs`) receives a share of the TX fee only when they are not the requester. If requester or validator is the creator, the creator’s share is folded into their respective percentage as described above.

package/msb.mjs

@@ -1,11 +1,12 @@
 import {MainSettlementBus} from './src/index.js';
 
-const isPear = typeof Pear !== 'undefined';
-const args = isPear ? Pear.config.args : process.argv.slice(2);
+const pearApp = typeof Pear !== 'undefined' ? (Pear.app ?? Pear.config) : undefined;
+const runtimeArgs = typeof process !== 'undefined' ? process.argv.slice(2) : [];
+const args = pearApp?.args ?? runtimeArgs;
 
 const opts = {
     stores_directory : 'stores/',
-    store_name : typeof process !== "undefined" ? process.argv[2] : Pear.config.args[0],
+    store_name : pearApp?.args?.[0] ?? runtimeArgs[0],
     bootstrap: 'acbc3a4344d3a804101d40e53db1dda82b767646425af73599d4cd6577d69685',
     channel: '0000trac0network0msb0mainnet0000',
     enable_role_requester: false,
@@ -21,6 +22,8 @@ const rpc_opts = {
     ...opts,
     enable_tx_apply_logs: false,
     enable_error_apply_logs: false,
+    enable_wallet: false,
+    enable_interactive_mode: true,
 
 }
 
@@ -44,4 +47,3 @@ msb.ready().then(async () => {
 
     msb.interactiveMode();
 });
-

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "trac-msb",
   "main": "msb.mjs",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "pear": {
     "name": "trac-msb",
     "type": "terminal"
@@ -9,11 +9,14 @@
   "type": "module",
   "scripts": {
     "dev": "pear run -d .",
-    "prod": "NODE_OPTIONS='--max-old-space-size=4096' pear run . ${npm_config_store}",
     "dev-rpc": "pear run -d . ${npm_config_store} --rpc --port ${npm_config_port}",
-    "prod-rpc": "pear run . ${npm_config_store} --rpc --host ${npm_config_host} --port ${npm_config_port}",
+    "prod": "NODE_OPTIONS='--max-old-space-size=4096' pear run . ${npm_config_store}",
+    "prod-rpc": "NODE_OPTIONS='--max-old-space-size=4096' pear run . ${npm_config_store} --rpc --host ${npm_config_host} --port ${npm_config_port}",
+    "env-prod": "if [ -f .env ]; then set -a; . ./.env; set +a; fi; NODE_OPTIONS='--max-old-space-size=4096' pear run . ${MSB_STORE:-node-store}",
+    "env-prod-rpc": "if [ -f .env ]; then set -a; . ./.env; set +a; fi; NODE_OPTIONS='--max-old-space-size=4096' pear run . ${MSB_STORE:-rpc-node-store} --rpc --host ${MSB_HOST:-127.0.0.1} --port ${MSB_PORT:-5000}",
+    "env-prod-rpc-docker": "if [ -f .env ]; then set -a; . ./.env; set +a; fi; NODE_OPTIONS='--max-old-space-size=4096' node msb.mjs ${MSB_STORE:-rpc-node-store} --rpc --host 0.0.0.0 --port ${MSB_PORT:-5000}",
     "protobuf": "node scripts/generate-protobufs.js",
-    "test:acceptance": "node --experimental-vm-modules node_modules/jest/bin/jest.js --testTimeout=200000 tests/acceptance/",
+    "test:acceptance": "node --experimental-vm-modules node_modules/jest/bin/jest.js --testTimeout=200000 tests/acceptance/v1/rpc.test.mjs --runInBand",
     "test:integration": "brittle-node -t 1200000 tests/integration/integration.test.js",
     "test:unit:node": "brittle-node -t 60000 tests/unit/unit.test.js",
     "test:unit:bare": "brittle-bare -t 60000 tests/unit/unit.test.js",
@@ -30,6 +33,7 @@
     "bare-http1": "4.1.5",
     "bare-readline": "1.0.7",
     "bare-tty": "5.0.2",
+    "bare-utils": "1.5.1",
     "bech32": "2.0.0",
     "compact-encoding": "2.18.0",
     "corestore": "7.5.0",

package/rpc/constants.mjs

@@ -1 +1,4 @@
-export const MAX_SIGNED_LENGTH = 1000
+import b4a from 'b4a';
+
+export const MAX_SIGNED_LENGTH = 1000;
+export const ZERO_WK = b4a.alloc(32).fill(0);