MSB Local setup

This page explains how to run and operate an MSB (Main Settlement Bus) node locally so you can:

• fund accounts (peer MSB addresses + wallet MSB addresses)

• deploy/check subnet registrations

• inspect txs and debug settlement

It does not modify the MSB repo; it only documents how to use it.

---

0) Glossary (quick)

• bootstrap: 32-byte hex id (64 hex chars) identifying the MSB Autobase.

• channel: discovery topic (string) that MSB nodes must share to find each other.

• store: local persisted data for one node (usually stores/<name>/...).

• MSB address: bech32m address like trac1....

• fee: MSB-level fee required to broadcast a transaction.

• confirmed vs unconfirmed (MSB): confirmed = signed state, unconfirmed = local unsigned view.

---

1) Prereqs

• Node.js + npm

• Pear (MSB scripts typically use Pear)

npm install -g pear
pear -v

Optional (if you run MSB tests):

npm install -g bare

---

2) Install MSB repo

From your workspace root:

git clone -b main --single-branch [email protected]:Trac-Systems/main_settlement_bus.git
cd main_settlement_bus
npm install

---

3) Run MSB locally

3.1 Interactive CLI node (recommended)

MSB_STORE=node1 npm run env-prod

This starts an interactive MSB node and stores data under main_settlement_bus/stores/node1/.

3.2 RPC node (optional)

MSB_STORE=rpc-node-store MSB_HOST=127.0.0.1 MSB_PORT=5000 npm run env-prod-rpc

---

4) Admin mode (if you need whitelisting/init)

MSB has extra admin-only commands (whitelisting, initialization migrations, banning). In the current MSB codebase, admin mode is inferred by store name:

MSB_STORE=admin npm run env-prod

---

5) MSB commands you’ll use most

Inside the MSB terminal, run /help for the full list. Common ones:

Network/state inspection

• /stats

• /confirmed_length

• /unconfirmed_length

• /get_fee

• /get_txv

Account inspection

• /get_balance <address> <confirmed> (confirmed defaults to true)

• /node_status <address>

Funding (critical for trac-peer)

To make an address “exist” in MSB state and have fee balance:

/transfer <to_address> <amount>

You must fund:

• each peer’s printed Peer MSB address (peer node operations)

• each wallet user MSB address (the requester) that will sign contract txs

If you don’t, you’ll see errors like:

• Requester address not found in state

• insufficient fee balance

Subnet deployment entries (for trac-peer)

• /deployment <subnet_bootstrap_hex32> <channel>

• /get_deployment <subnet_bootstrap_hex32>

Tx lookup / debugging

• /get_tx_info <tx_hash>

• /get_tx_details <tx_hash>

• /get_extended_tx_details <tx_hash> <confirmed>

• /get_txs_hashes <start> <end>

---

6) Whitelisting + initial balances (optional bootstrap workflow)

MSB supports an initialization phase that reads from files:

• main_settlement_bus/migration/initial_balances.csv

• main_settlement_bus/whitelist/addresses.csv

In an MSB admin terminal you can run:

• /balance_migration

• /add_whitelist

• /disable_initialization

---

7) Next: run trac-peer

Once MSB is running and you know:

• MSB_BOOTSTRAP

• MSB_CHANNEL

continue with:

• 11-bootstrap-checklist.md (canonical A→Z checklist)