Skip to content

txncache: spill to disk #11581

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ibhatt-jumptrading merged 2 commits into from
Oct 30, 2026
+2,877 −1,388
Merged

txncache: spill to disk #11581

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8f01508
txncache: spill to disk
ibhatt-jumptrading Oct 29, 2026
e104cdb
snapin: stage status cache groups in the txncache spill file
ibhatt-jumptrading Oct 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions book/api/metrics-generated.md
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

1 change: 1 addition & 0 deletions contrib/ci/bench/bench.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ telemetry = false
enabled = false
[runtime]
max_live_slots = 256
transaction_cache_size_mib = 3072
[accounts]
max_accounts = 4000000
cache_size_gib = 3
Expand Down
3 changes: 2 additions & 1 deletion src/app/firedancer-dev/commands/backtest.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -407,7 +407,7 @@ backtest_topo( config_t * config ) {
FD_TEST( fd_pod_insertf_ulong( topo->props, banks_obj->id, "banks" ) );

fd_topob_wksp( topo, "txncache" );
fd_topo_obj_t * txncache_obj = setup_topo_txncache( topo, "txncache", config->firedancer.runtime.max_live_slots, 2UL*config->limits.max_txn_per_slot );
fd_topo_obj_t * txncache_obj = setup_topo_txncache( topo, "txncache", config->firedancer.runtime.max_live_slots, 2UL*config->limits.max_txn_per_slot, config->firedancer.runtime.transaction_cache_size_mib<<20 );
fd_topob_tile_uses( topo, replay_tile, txncache_obj, FD_SHMEM_JOIN_MODE_READ_WRITE );
if( FD_LIKELY( !disable_snap_loader ) ) {
fd_topob_tile_uses( topo, &topo->tiles[ fd_topo_find_tile( topo, "snapin", 0UL ) ], txncache_obj, FD_SHMEM_JOIN_MODE_READ_WRITE );
Expand Down Expand Up @@ -539,6 +539,7 @@ backtest_cmd_fn( args_t * args,
initialize_cost_tracker_fd( config );
initialize_vote_stakes_fd( config );
initialize_stake_delegations_fd( config );
initialize_txncache_fd( config );
initialize_store_fds( config );
initialize_snapshot_fds( config );

Expand Down
3 changes: 2 additions & 1 deletion src/app/firedancer-dev/commands/snapshot_load.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -116,7 +116,7 @@ snapshot_load_topo( config_t * config ) {
fd_topob_wksp( topo, "txncache" );
fd_topo_obj_t * txncache_obj = setup_topo_txncache( topo, "txncache",
config->firedancer.runtime.max_live_slots,
2UL*config->limits.max_txn_per_slot );
2UL*config->limits.max_txn_per_slot, config->firedancer.runtime.transaction_cache_size_mib<<20 );
FD_TEST( fd_pod_insertf_ulong( topo->props, txncache_obj->id, "txncache" ) );

fd_topob_wksp( topo, "accdb" );
Expand Down Expand Up @@ -496,6 +496,7 @@ snapshot_load_cmd_fn( args_t * args,
initialize_cost_tracker_fd( config );
initialize_vote_stakes_fd( config );
initialize_stake_delegations_fd( config );
initialize_txncache_fd( config );
initialize_store_fds( config );
initialize_snapshot_fds( config );

Expand Down
4 changes: 2 additions & 2 deletions src/app/firedancer/callbacks.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -182,7 +182,7 @@ fd_topo_obj_callbacks_t fd_obj_cb_accdb = {
static ulong
txncache_footprint( fd_topo_t const * topo,
fd_topo_obj_t const * obj ) {
return fd_txncache_shmem_footprint( VAL("max_live_slots"), VAL("max_txn_per_slot") );
return fd_txncache_shmem_footprint( VAL("max_live_slots"), VAL("max_txn_per_slot"), VAL("cache_footprint") );
}

static ulong
Expand All @@ -194,7 +194,7 @@ txncache_align( fd_topo_t const * topo FD_FN_UNUSED,
static void
txncache_new( fd_topo_t const * topo,
fd_topo_obj_t const * obj ) {
FD_TEST( fd_txncache_shmem_new( fd_topo_obj_laddr( topo, obj->id ), VAL("max_live_slots"), VAL("max_txn_per_slot"), VAL("seed") ) );
FD_TEST( fd_txncache_shmem_new( fd_topo_obj_laddr( topo, obj->id ), VAL("max_live_slots"), VAL("max_txn_per_slot"), VAL("cache_footprint"), VAL("seed") ) );
}

fd_topo_obj_callbacks_t fd_obj_cb_txncache = {
Expand Down
3 changes: 3 additions & 0 deletions src/app/firedancer/config/bench-zen3-32core.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,9 @@
shred_tile_count = 1
sign_tile_count = 2

[runtime]
transaction_cache_size_mib = 3072

[development.genesis]
fund_initial_accounts = 32768

Expand Down
3 changes: 3 additions & 0 deletions src/app/firedancer/config/bench-zen4-128core.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,9 @@
shred_tile_count = 1
sign_tile_count = 2

[runtime]
transaction_cache_size_mib = 3072

[development.genesis]
fund_initial_accounts = 32768

Expand Down
18 changes: 18 additions & 0 deletions src/app/firedancer/config/default.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -248,6 +248,16 @@ telemetry = true
# Firedancer instance.
vote_stakes = ""

# File path used to create the temporary transaction-cache spill
# file. If no path is provided, it defaults to the `txncache.db`
# path within the base directory above.
#
# Two substitutions will be performed on this string. If "{user}"
# is present it will be replaced with the user running Firedancer,
# as above, and "{name}" will be replaced with the name of the
# Firedancer instance.
txncache = ""

# File path to the shreds database file.
#
# The shreds database stores recorded and reconstructed shreds
Expand Down Expand Up @@ -817,6 +827,14 @@ telemetry = true
# or test environments to decrease memory usage or test edge cases.
bank_cache_cnt = 16

# Memory budget for cached transactions in MiB, excluding metadata.
# When full, the cache spills to paths.txncache. This value has
# been chosen and tuned around mainnet network behavior.
#
# It is not recommended to change this value, except in development
# or test environments to decrease memory usage to test edge cases.
transaction_cache_size_mib = 480

# CPU cores in Firedancer are carefully managed. Where a typical
# program lets the operating system scheduler determine which threads to
# run on which cores and for how long, Firedancer overrides most of this
Expand Down
8 changes: 4 additions & 4 deletions src/app/firedancer/topology.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,8 +23,6 @@
#include "../../discof/restore/fd_snapct_tile.h"
#include "../../disco/gui/fd_gui_config_parse.h"
#include "../../disco/quic/fd_tpu.h"
#include "../../disco/pack/fd_pack_cost.h"
#include "../../disco/pack/fd_pack.h"
#include "../../disco/tiles.h"
#include "../../disco/topo/fd_topob.h"
#include "../../disco/topo/fd_cpu_topo.h"
Expand Down Expand Up @@ -208,13 +206,15 @@ fd_topo_obj_t *
setup_topo_txncache( fd_topo_t * topo,
char const * wksp_name,
ulong max_live_slots,
ulong max_txn_per_slot ) {
ulong max_txn_per_slot,
ulong cache_footprint ) {
ulong seed;
FD_TEST( fd_rng_secure( &seed, sizeof( ulong ) ) );

fd_topo_obj_t * obj = fd_topob_obj( topo, "txncache", wksp_name );
FD_TEST( fd_pod_insertf_ulong( topo->props, max_live_slots, "obj.%lu.max_live_slots", obj->id ) );
FD_TEST( fd_pod_insertf_ulong( topo->props, max_txn_per_slot, "obj.%lu.max_txn_per_slot", obj->id ) );
FD_TEST( fd_pod_insertf_ulong( topo->props, cache_footprint, "obj.%lu.cache_footprint", obj->id ) );
FD_TEST( fd_pod_insertf_ulong( topo->props, seed, "obj.%lu.seed", obj->id ) );

return obj;
Expand Down Expand Up @@ -1179,7 +1179,7 @@ fd_topo_initialize( config_t * config ) {
if( rserve_enabled ) fd_topob_tile_uses( topo, &topo->tiles[ fd_topo_find_tile( topo, "rserve", 0UL ) ], store_obj, FD_SHMEM_JOIN_MODE_READ_WRITE );
FD_TEST( fd_pod_insertf_ulong( topo->props, store_obj->id, "store" ) );

fd_topo_obj_t * txncache_obj = setup_topo_txncache( topo, "txncache", config->firedancer.runtime.max_live_slots, 2UL*config->limits.max_txn_per_slot /* sig + message hash */ );
fd_topo_obj_t * txncache_obj = setup_topo_txncache( topo, "txncache", config->firedancer.runtime.max_live_slots, 2UL*config->limits.max_txn_per_slot /* sig + message hash */, config->firedancer.runtime.transaction_cache_size_mib<<20 );
fd_topob_tile_uses( topo, &topo->tiles[ fd_topo_find_tile( topo, "replay", 0UL ) ], txncache_obj, FD_SHMEM_JOIN_MODE_READ_WRITE );
if( FD_LIKELY( snapshots_enabled ) ) {
fd_topob_tile_uses( topo, &topo->tiles[ fd_topo_find_tile( topo, "snapin", 0UL ) ], txncache_obj, FD_SHMEM_JOIN_MODE_READ_WRITE );
Expand Down
3 changes: 2 additions & 1 deletion src/app/firedancer/topology.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,8 @@ fd_topo_obj_t *
setup_topo_txncache( fd_topo_t * topo,
char const * wksp_name,
ulong max_live_slots,
ulong max_txn_per_slot );
ulong max_txn_per_slot,
ulong cache_footprint );
Comment on lines +73 to +74

void
fd_topo_configure_tile( fd_topo_tile_t * tile,
Expand Down
22 changes: 22 additions & 0 deletions src/app/shared/commands/run/run.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
#include "../../../../flamenco/runtime/fd_cost_tracker_store.h"
#include "../../../../flamenco/stakes/fd_vote_stakes.h"
#include "../../../../flamenco/stakes/fd_stake_delegations.h"
#include "../../../../flamenco/runtime/fd_txncache.h"
#include "../../../../disco/store/fd_store.h"

#include <sys/wait.h>
Expand Down Expand Up @@ -362,6 +363,7 @@ main_pid_namespace( void * _args ) {
initialize_cost_tracker_fd( config );
initialize_vote_stakes_fd( config );
initialize_stake_delegations_fd( config );
initialize_txncache_fd( config );
initialize_store_fds( config );
ulong store_obj_id = fd_pod_query_ulong( config->topo.props, "store", ULONG_MAX );
int has_store = store_obj_id!=ULONG_MAX;
Expand Down Expand Up @@ -449,6 +451,12 @@ main_pid_namespace( void * _args ) {
if( FD_UNLIKELY( -1==fcntl( FD_ACCDB_FD_RO, F_SETFD, FD_CLOEXEC ) ) ) FD_LOG_ERR(( "fcntl(F_SETFD,FD_CLOEXEC) failed (%i-%s)", errno, fd_io_strerror( errno ) ));
}

ulong txncache_obj_id = fd_pod_query_ulong( config->topo.props, "txncache", ULONG_MAX );
int tile_uses_txncache = 0;
for( ulong i=0UL; i<tile->uses_obj_cnt; i++ ) tile_uses_txncache |= tile->uses_obj_id[ i ]==txncache_obj_id;
if( FD_UNLIKELY( fcntl( FD_TXNCACHE_FD, F_SETFD, tile_uses_txncache ? 0 : FD_CLOEXEC )<0 ) )
FD_LOG_ERR(( "fcntl(FD_TXNCACHE_FD,F_SETFD) failed (%i-%s)", errno, fd_io_strerror( errno ) ));

if( FD_LIKELY( has_store ) ) {
int tile_uses_store = 0;
for( ulong i=0UL; i<tile->uses_obj_cnt; i++ ) tile_uses_store |= tile->uses_obj_id[ i ]==store_obj_id;
Expand Down Expand Up @@ -547,6 +555,7 @@ main_pid_namespace( void * _args ) {

if( FD_UNLIKELY( -1==close( FD_ACCDB_FD_RW ) ) ) FD_LOG_ERR(( "close() failed (%i-%s)", errno, fd_io_strerror( errno ) ));
if( FD_UNLIKELY( -1==close( FD_ACCDB_FD_RO ) ) ) FD_LOG_ERR(( "close() failed (%i-%s)", errno, fd_io_strerror( errno ) ));
if( FD_UNLIKELY( -1==close( FD_TXNCACHE_FD ) ) ) FD_LOG_ERR(( "close() failed (%i-%s)", errno, fd_io_strerror( errno ) ));
if( FD_LIKELY( has_store ) ) {
if( FD_UNLIKELY( -1==close( FD_STORE_FD_RW ) ) ) FD_LOG_ERR(( "close() failed (%i-%s)", errno, fd_io_strerror( errno ) ));
if( FD_UNLIKELY( -1==close( FD_STORE_FD_RO ) ) ) FD_LOG_ERR(( "close() failed (%i-%s)", errno, fd_io_strerror( errno ) ));
Expand Down Expand Up @@ -1161,6 +1170,19 @@ initialize_stake_delegations_fd( config_t const * config ) {
}
}

void
initialize_txncache_fd( config_t const * config ) {
char const * spill_path = config->paths.txncache;
int spill_fd = open( spill_path, O_RDWR|O_CREAT|O_TRUNC|O_NOATIME|O_DIRECT, S_IRUSR|S_IWUSR );
Comment thread
ibhatt-jumptrading marked this conversation as resolved.
Resolved
if( FD_UNLIKELY( -1==spill_fd ) ) FD_LOG_ERR(( "failed to open %s (%i-%s)", spill_path, errno, fd_io_strerror( errno ) ));
if( FD_UNLIKELY( -1==unlink( spill_path ) ) ) FD_LOG_ERR(( "unlink(%s) failed (%i-%s)", spill_path, errno, fd_io_strerror( errno ) ));

if( FD_LIKELY( spill_fd!=FD_TXNCACHE_FD ) ) {
if( FD_UNLIKELY( -1==dup2( spill_fd, FD_TXNCACHE_FD ) ) ) FD_LOG_ERR(( "dup2() failed (%i-%s)", errno, fd_io_strerror( errno ) ));
if( FD_UNLIKELY( -1==close( spill_fd ) ) ) FD_LOG_ERR(( "close() failed (%i-%s)", errno, fd_io_strerror( errno ) ));
}
}

void
initialize_store_fds( config_t const * config ) {
fd_topo_t const * topo = &config->topo;
Expand Down
3 changes: 3 additions & 0 deletions src/app/shared/commands/run/run.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,9 @@ initialize_vote_stakes_fd( config_t const * config );
void
initialize_stake_delegations_fd( config_t const * config );

void
initialize_txncache_fd( config_t const * config );

void
initialize_store_fds( config_t const * config );

Expand Down
11 changes: 11 additions & 0 deletions src/app/shared/fd_config.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -156,6 +156,13 @@ fd_config_fillf( fd_config_t * config ) {
FD_TEST( fd_cstr_printf_check( config->paths.vote_stakes, sizeof(config->paths.vote_stakes), NULL, "%s/votestakes.db", config->paths.base ) );
}

if( FD_UNLIKELY( strcmp( config->paths.txncache, "" ) ) ) {
replace( config->paths.txncache, "{user}", config->user );
replace( config->paths.txncache, "{name}", config->name );
Comment on lines +159 to +161
} else {
FD_TEST( fd_cstr_printf_check( config->paths.txncache, sizeof(config->paths.txncache), NULL, "%s/txncache.db", config->paths.base ) );
}

if( FD_UNLIKELY( strcmp( config->paths.shredb, "" ) ) ) {
replace( config->paths.shredb, "{user}", config->user );
replace( config->paths.shredb, "{name}", config->name );
Expand Down Expand Up @@ -517,6 +524,10 @@ fd_config_validatef( fd_configf_t const * config ) {
}

CFG_HAS_NON_ZERO( runtime.program_cache_size_mib );
CFG_HAS_NON_ZERO( runtime.transaction_cache_size_mib );
Comment thread
ibhatt-jumptrading marked this conversation as resolved.
Resolved
if( FD_UNLIKELY( config->runtime.transaction_cache_size_mib>(ULONG_MAX>>20) ) ) {
FD_LOG_ERR(( "runtime.transaction_cache_size_mib is too large: %lu", config->runtime.transaction_cache_size_mib ));
}
}

void
Expand Down
2 changes: 2 additions & 0 deletions src/app/shared/fd_config.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,7 @@ struct fd_configf {
ulong stake_delegation_cache_cnt;
ulong program_cache_size_mib;
ulong bank_cache_cnt;
ulong transaction_cache_size_mib;
} runtime;

struct {
Expand Down Expand Up @@ -224,6 +225,7 @@ struct fd_config {
char epoch_credits[ PATH_MAX ];
char cost_tracker[ PATH_MAX ];
char vote_stakes[ PATH_MAX ];
char txncache[ PATH_MAX ];
char shredb[ PATH_MAX ];
char guidb[ PATH_MAX ];
char vote_history[ PATH_MAX ];
Expand Down
5 changes: 4 additions & 1 deletion src/app/shared/fd_config_json.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
or knowingly skipped) before the constant is bumped. String keys of
the user's own file are separately forced through the classification
lists below. */
FD_STATIC_ASSERT( sizeof(fd_config_t)==24458384UL, update_fd_config_to_json_for_the_layout_change );
FD_STATIC_ASSERT( sizeof(fd_config_t)==24462488UL, update_fd_config_to_json_for_the_layout_change );

#define REDACTED "[redacted]"

Expand Down Expand Up @@ -118,6 +118,7 @@ static char const * const jw_redacted_keys[] = {
"paths.epoch_credits",
"paths.cost_tracker",
"paths.vote_stakes",
"paths.txncache",
"paths.shredb",
"paths.guidb",
"paths.vote_history",
Expand Down Expand Up @@ -327,6 +328,7 @@ fd_config_to_json( fd_config_t const * config,
jw_path( &w, "epoch_credits", config->paths.epoch_credits );
jw_path( &w, "cost_tracker", config->paths.cost_tracker );
jw_path( &w, "vote_stakes", config->paths.vote_stakes );
jw_path( &w, "txncache", config->paths.txncache );
jw_path( &w, "shredb", config->paths.shredb );
jw_path( &w, "guidb", config->paths.guidb );
jw_path( &w, "vote_history", config->paths.vote_history );
Expand Down Expand Up @@ -385,6 +387,7 @@ fd_config_to_json( fd_config_t const * config,
jw_ulong( &w, "stake_delegation_cache_cnt", f->runtime.stake_delegation_cache_cnt );
jw_ulong( &w, "program_cache_size_mib", f->runtime.program_cache_size_mib );
jw_ulong( &w, "bank_cache_cnt", f->runtime.bank_cache_cnt );
jw_ulong( &w, "transaction_cache_size_mib", f->runtime.transaction_cache_size_mib );
jw_obj_close( &w );

jw_obj_open( &w, "snapshots" );
Expand Down
Loading
Loading