Skip to main content

Build and test

The protocol is a Rust workspace. burst-daemon runs a node; burst-wallet-core contains the client and signing code used by the desktop wallet. The wallet and dashboard are separate Tauri applications.

Build the daemon​

Install Rust through rustup, Git, and your platform's C/C++ build tools. The repository's rust-toolchain.toml selects the Rust version. Use the committed Cargo lockfile.

git clone https://github.com/BURST-UBI/protocol.git
cd protocol
cargo build --locked -p burst-daemon

The executable is target/debug/burst-daemon (burst-daemon.exe on Windows). Use a debug build for development. A release build uses --release and writes to target/release/.

If this checkout has an AGENTS.md with local resource limits, follow it when running these commands. The project's tools/limited-run.sh is a Linux systemd wrapper for that constrained development environment, not a prerequisite for building BURST on another machine.

Start a local node​

From the protocol directory:

./target/debug/burst-daemon --network dev --data-dir .dev_docs_node \
  --port 27076 --rpc --rpc-port 7077 --websocket --websocket-port 7078 \
  --faucet --disable-upnp node run

This runs in the foreground. Stop it with Ctrl+C. The data directory persists between runs; use a different directory when you need a separate network or a fresh ledger. RPC listens on 127.0.0.1:7077, and WebSocket subscriptions use ws://127.0.0.1:7078/ws.

Check that RPC is responding:

curl --fail http://127.0.0.1:7077/health
curl http://127.0.0.1:7077/ \
  -H 'Content-Type: application/json' \
  -d '{"action":"telemetry"}'

/health returns ok. telemetry reports the selected network, peer count, account count and other node state. A local Dev node need not have public peers. For a multi-node network, supply --bootstrap-peers HOST:PORT and use the same network identity on every node.

For file-based configuration, use --config PATH before node run. Node configuration lists common settings.

Create and fund a test wallet​

Create the wallet in the desktop application or with the client-side key APIs. Do not use wallet_create RPC to create an account you intend to spend from: that handler discards the private key.

With --faucet enabled on Dev or Test, request a payment to your disposable wallet address:

curl http://127.0.0.1:7077/ \
  -H 'Content-Type: application/json' \
  -d '{"action":"faucet","account":"YOUR_DISPOSABLE_WALLET_ADDRESS"}'

The faucet burns one BRN from the network's genesis account and sends one TRST. It needs genesis authority and enough accrued BRN. The recipient still signs a receive operation. Funding does not verify the recipient.

For a small bootstrap network, receive the payment and set a running representative before verifying another account. Otherwise its newly added voting weight may be delegated to an offline representative. The creator's genesis_endorse RPC requires an administrator bearer token; see bootstrap permissions and RPC access controls.

Feature flags​

Ordinary verifier selection, appeals, governance content and ledger-backed voting delegation have release switches. To exercise experimental paths on Dev or Test, build the daemon with:

cargo build --locked -p burst-daemon --features experimental-testnet

This flag does not enable those paths on Live. See feature availability. Keep separate data directories for Dev, Test and Live.

Run tests​

Start with the crate you changed:

cargo test --locked -p burst-types
cargo test --locked -p burst-brn
cargo test --locked -p burst-trst

The node test runner groups the larger suite:

bash tools/test-node.sh fast
bash tools/test-node.sh slow
bash tools/test-node.sh network
bash tools/test-node.sh focused checkpoints::sync::input::tests::slow_polls_and_busy_inbox_both_make_progress

focused takes an exact test name. The runner uses the validation profile; BURST_NODE_TEST_BINARY can select an already-built matching executable. Network tests run serially by default. Check each ignored test's prerequisites before enabling it.

For multi-node payment and restart tests, run-validation.sh takes prebuilt artifacts. It does not compile them:

bash run-validation.sh --artifacts-dir "$PWD/target/debug"

The directory must contain burst-daemon and the wallet-core examples validate_network, validate_restart_payment and validate_pending_chain. The runner checks ports and saves its logs. Use the validation workflow for release-candidate testing and reuse of recorded results.

Build the desktop applications​

Use sibling checkouts:

burst/
  protocol/
  wallet/
  node-gui/

In wallet/ or node-gui/, install Node.js, the platform dependencies required by Tauri, then run:

npm ci
npm run tauri dev

Both applications default to RPC at http://127.0.0.1:7077. npm run dev starts only the frontend; it does not provide native key storage or signing. Use disposable profiles when testing payments or recovery.

Application CI fetches the protocol revision recorded in each application's ci/protocol-revision. If you change a shared Rust API, update the affected application and its pin together. A local sibling checkout can otherwise hide an incompatibility with the revision CI builds.

Documentation changes​

Edit docs/ and its SUMMARY.md navigation here. The website source and build instructions live in BURST-UBI/whitepaper. It renders these files from the protocol commit recorded in its protocol-source.json; there is no second editable copy of the docs. Website dependencies and deployment configuration belong in that repository.

The build checks internal links and generates local search. Keep code examples consistent with the RPC contracts in rpc/messages/ and the public methods in wallet_core/. Put machine-specific test receipts in engineering records, not in user-facing setup instructions.

View Markdown