Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

FireBAM Setup Guide

FireBAM is a fork of Firedancer that adds support for BAM (Blockspace Assembly Marketplace). BAM provides next-generation transaction scheduling for Solana while the validator continues to own consensus, voting, execution, and block production.

This guide covers the FireBAM-specific setup. Before continuing, complete the standard Firedancer installation and host configuration:

How FireBAM Works

The BAM node receives transactions and Block Engine bundles, schedules them, and sends ordered work to the validator over gRPC. FireBAM executes that work and returns leader-state and execution results to the BAM node.

FireBAM has two operating modes:

  • BAM disabled or unhealthy: the BAM scheduling path is inactive and the validator uses its normal transaction ingress, including Block Engine.

  • BAM enabled and healthy: the validator accepts scheduled work from the BAM node. Normal TPU and Block Engine bundle ingress are paused while this mode is active.

Requirements

All standard Firedancer requirements still apply. The current FireBAM release has been tested with:

  • Ubuntu 24.04

  • An AVX-512-compatible CPU, such as Intel Ice Lake or later or AMD EPYC 9xxx

  • At least 386 GiB of RAM

  • A 10 Gbit/s or faster network connection

  • Outbound DNS and TCP access to the selected BAM endpoint on ports 50055-50056

Get FireBAM

FireBAM is available from the Jito FireBAM repository. Select the intended release, then clone the repository with its submodules:

Build the binary for the validator mode you operate.

Build Firedancer

The binary is written to build/native/gcc/bin/firedancer.

Build Frankendancer

Build fdctl for a production validator:

The binary is written to build/native/gcc/bin/fdctl.

For development and test environments, you can also build fddev or firedancer-dev:

The binary is written to build/native/gcc/bin/.

Configure FireBAM

Start with the Firedancer configuration you already use for the target cluster. Keep your normal identity, vote account, authorized voter, ledger, accounts, gossip, snapshot, RPC, and reporting settings.

The same BAM and Block Engine settings apply to Firedancer and Frankendancer. Add the sections for your cluster.

Mainnet

commission_bps is the validator’s tip commission in basis points. Set it to the value you intend to use rather than copying the example without review.

Testnet

The bundle and BAM tiles do not support hot reconfiguration. To use bundle functionality, [tiles.bundle].enabled = true must be present when the validator starts. To use BAM functionality, [tiles.bam].enabled = true must be present when the validator starts. If either tile is not enabled at startup, the validator must be restarted with the corresponding setting enabled before that functionality can be used.

Start FireBAM

Replace mainnet.toml with the path to your reviewed configuration. Run only the command for your validator mode.

Firedancer

Use the appropriate checked-in BAM configuration as a reference:

Frankendancer

Use the appropriate checked-in BAM configuration as a reference:

Use fdctl for a production validator:

Run FireBAM under the same service supervision and restart policy you use for your validator, and use that supervisor to stop it. Do not run a second validator process against the same identity, ledger, or accounts directories.

Verify the BAM Tile

In another shell, inspect the configured topology with the binary for your validator mode.

Inspect the configured topology

Firedancer

Frankendancer

You should see the BAM tile and its related workspaces. If the Firedancer GUI is enabled, the topology should also contain bam:0.

Check the runtime BAM configuration

Firedancer

Frankendancer

Always pass the same configuration file that was used to start the validator.

Runtime Control

You can change the BAM endpoint or toggle BAM without restarting, provided the validator started with [tiles.bam].enabled = true.

Update the BAM configuration

Firedancer

Frankendancer

Change the validator identity

Identity changes use the control binary for the running validator mode.

Firedancer

Frankendancer

Use --force only when intentionally recovering from a partially completed identity change.

Monitor FireBAM

Read metrics

If HTTP metrics are enabled, the same command works for both validator modes:

If HTTP metrics are disabled, use the control binary for your validator mode.

Firedancer

Frankendancer

Core BAM Health

Metric
Meaning

bam_enabled

Operator enable state: 1 when BAM is enabled and 0 when disabled

bam_healthy

1 when transport, authentication, configuration, scheduler stream, and builder-activity checks are healthy; it does not guarantee that fresh work has arrived for the current leader slot

bam_stream_live

1 when the BAM scheduler gRPC stream is established and live

bam_transaction_published_total

Transactions published from BAM to verify, including transactions unpacked from bundles

bam_atomic_batch_published_total

revert_on_error atomic batches published from BAM to verify

bam_failure_total

BAM control-plane and session failures grouped by class; scheduler payload and atomic-batch rejections are counted separately

Pack Progress

Metric
Meaning

pack_bam_work_items_total

BAM work items observed at each labeled pack lifecycle stage; a multi-transaction bundle counts as one item

pack_bam_pending_work_count

Current BAM work items tracked after acceptance and before scheduling or cleanup

pack_bam_leader_slot_first_insert_result_total

Leader slots grouped by no BAM insert, first insert before slot end, or first insert at or after slot end

pack_bam_leader_slot_first_schedule_result_total

Leader slots grouped by no BAM schedule, first schedule before slot end, or first schedule at or after slot end

pack_bam_work_first_outcome_total

BAM work items grouped by their first terminal pack outcome

Metrics ending in _total are cumulative counters. Use their labels and rates or increases when building alerts; pack_bam_pending_work_count is a current gauge.

Troubleshooting

The BAM tile is missing

Confirm that the configuration contained [tiles.bam].enabled = true before startup. Add it and restart the validator; set-bam cannot create a missing BAM topology at runtime.

get-bam reports that runtime control is unavailable

Use the exact configuration path that started the validator. If the error continues, confirm the validator started with BAM enabled and restart it after correcting the configuration.

bam_enabled=1 but bam_healthy=0

Check:

  • The BAM hostname, port, and cluster

  • DNS resolution and outbound TCP connectivity to ports 50055-50056

  • Validator identity access and BAM authentication logs

  • If bam_stream_live=0, scheduler-stream connection errors and the labeled failure classes in bam_failure_total

  • If bam_stream_live=1, configuration-response errors, missing builder heartbeats, or builder-activity timeouts in the validator log

Hugepage or shared-memory errors

Stop the validator before changing hugepage mounts. The following commands remove and recreate the hugetlbfs mounts and named shared-memory regions for the supplied configuration, so use the exact configuration file for the stopped validator.

Firedancer

Frankendancer

Last-resort host configuration reset

Use this only when targeted recovery has failed. Stop the validator and any other process using its hugepage mounts, CPU cores, or network interfaces. Disable automatic supervisor restarts until the reset is complete, and use the exact configuration file for the stopped validator.

configure fini all undoes every host-configuration stage that the selected binary can roll back. configure init all then checks and reapplies every stage known to that binary, including stages that do not support rollback. This is a full rebuild of the configuration managed by the selected binary, not a factory reset of the host.

Area
Firedancer
Frankendancer

Hugepage mounts and named shared-memory regions

Removed and recreated

Removed and recreated

System-wide reserved hugepage counts

Increased if required by init; not reduced by fini

Increased if required by init; not reduced by fini

Cpuset, IRQ affinity, irqbalance, and kernel-worker CPU masks

Reset and reapplied where supported

Not managed by fdctl

Kernel and network tuning

Reset where a rollback handler exists, then checked and reapplied

Reset where a rollback handler exists, then checked and reapplied

Agave or systemd CPU affinity

Not managed; restore through the owning service configuration

Not managed; restore through the owning service configuration

These commands change host-wide memory, CPU, kernel, and network configuration. If configure fini all reports that a resource is still in use, stop the process using it instead of forcing the cleanup. Do not proceed until configure fini all completes successfully; then run configure init all.

Firedancer

Frankendancer

Next Steps

After FireBAM is healthy:

  1. Confirm bam_enabled=1, bam_healthy=1, and bam_stream_live=1.

  2. Confirm bam_transaction_published_total and, when atomic batches arrive, bam_atomic_batch_published_total increase.

  3. During leader slots, confirm the labeled pack_bam_work_items_total stages progress and the first-insert and first-schedule results occur before slot end.

  4. Alert on BAM health or stream loss and unexpected increases in no_event or after_end first-insert and first-schedule results.

For BAM architecture and validator information, see bam.dev and the BAM validator guide.

PreviousChecking Correct Operation
NextFAQs

Last updated