cuprated: embeddable node library with `Node::launch()` by redsh4de · Pull Request #592 · Cuprate/cuprate

redsh4de · 2026-03-16T15:41:11Z

What

Extracts cuprated into an embeddable library (lib.rs/main.rs pattern). Takes inspiration from the API proposed in #554

Closes #516

Note to reviewers: This does not implement graceful shutdown / panic removal yet, those have been deferred to #585. For the final state with all changes, skip to #590

Why

To enable embedding the node in other applications

Where

cuprated:
- Cargo.toml - explicit [lib] + [[bin]] targets
- lib.rs - new: Node struct, NodeContext for shared state, Node::launch(), public service handles
- main.rs - simplified to CLI wrapper calling Node::launch()
- commands.rs - actor pattern rewrite: CommandHandle with mpsc/oneshot, send_command() API
- config.rs - decoupled from CLI args, find_config() returns Result<Option<Config>>, removed process::exit from library code
- blockchain/syncer.rs - SyncNotify renamed to SyncState
- blockchain/interface.rs - free functions + statics (COMMAND_TX, BLOCKS_BEING_HANDLED) converted to BlockchainManagerHandle struct with owned channel + lock
- version.rs - add Default impl (thanks clippy)
- Removed mutable statics in favor of NodeContext for multi-instance support
consensus/fast-sync:
- Removed global FAST_SYNC_HASHES static
- set_fast_sync_hashes removed; fast_sync_stop_height and validate_entries now take hashes as a parameter from NodeContext

How

Node::launch(config) in lib.rs handles all initialization and returns a Node with service handles that serve as the API to the embeder:

pub struct Node {
    pub context: BlockchainContextService,
    pub blockchain: BlockchainReadHandle,
    pub txpool: TxpoolReadHandle,
    pub clearnet: NetworkInterface<ClearNet>,
    pub tor: Option<oneshot::Receiver<NetworkInterface<Tor>>>,
    pub syncer: SyncerHandle,
    pub command: CommandHandle,
}

The previous mutable statics were moved into NodeContext, making the node safe to run multiple times in a single process.

pub struct NodeContext {
    pub network: Network,
    pub fast_sync_hashes: &'static [[u8; 32]], /// was static
    pub reorg_lock: Arc<RwLock<()>>, // was static
    pub blockchain_manager: BlockchainManagerHandle, // was composed of statics
    pub blockchain_read: BlockchainReadHandle,
    pub blockchain_context: BlockchainContextService,
    pub txpool_read: TxpoolReadHandle,
    pub syncer: SyncerHandle,
    pub start_instant: std::time::SystemTime,
    pub start_instant_unix: u64,
}

BlockchainManagerHandle replaces the COMMAND_TX and BLOCKS_BEING_HANDLED statics from interface.rs, wrapping them into a struct with new(), is_block_being_handled(), and handle_incoming_block() methods.

The Tor interface arrives via oneshot after sync, similar to the dandelion.rs pattern.

sneurlax · 2026-03-19T03:21:58Z

binaries/cuprated/src/lib.rs

+    /// Panics if the database is corrupt or critical services fail to start.
+    pub async fn launch(config: Config) -> Self {
+        // Initialize global static `LazyLock` data.
+        statics::init_lazylock_statics();


statics::init_lazylock_statics() twice--once in main.rs, once here. What should actually be responsible for this?

Ideally this should be called by the embedder imo.

However, it's kept twice because if it's called a second time, it's a no-op, and if the embedder doesnt do it the library will take care of it

sneurlax · 2026-03-19T03:24:15Z

binaries/cuprated/src/lib.rs

+        let (mut blockchain_read_handle, mut blockchain_write_handle, _) =
+            cuprate_blockchain::service::init_with_pool(
+                config.blockchain_config(),
+                Arc::clone(&db_thread_pool),
+            )
+            .inspect_err(|e| error!("Blockchain database error: {e}"))
+            .expect(DATABASE_CORRUPT_MSG);


won't this panic if the db is corrupt, misconfigured, etc? maybe locked?

inspect_err logs it then panics anyways?

It will - the graceful shutdown PRs that are dependant on this branch gradually introduce error propagation and get rid of the expects

They are split into parts so that its easier to review, as the changes there are quite verbose

sneurlax · 2026-03-19T03:25:05Z

binaries/cuprated/src/lib.rs

+        let (txpool_read_handle, txpool_write_handle, _) =
+            cuprate_txpool::service::init_with_pool(&config.txpool_config(), db_thread_pool)
+                .inspect_err(|e| error!("Txpool database error: {e}"))
+                .expect(DATABASE_CORRUPT_MSG);


same thing here, will this panic if the db is corrup tor locked?

Same as prior, deferred to the other three graceful shutdown PRs

sneurlax · 2026-03-19T03:26:57Z

binaries/cuprated/src/lib.rs

+        let context_svc =
+            blockchain::init_consensus(blockchain_read_handle.clone(), config.context_config())
+                .await
+                .unwrap();


this naked unwrap can cause a panic w no useful msg if consensus init fails

Deferred to PR #586

sneurlax · 2026-03-19T03:34:17Z

you should try and return something like Result<Self, NodeInitError> rather than panicking

I don't get the difference between or relative purposes of Node and NodeContext. Which should be used for what?

with dry_run_check calling std::process::exit(code), won't an embedder calling config.dry_run_check() get their process killed?

nit but SyncState renamed unnecessarily imo

there's no way to shut it down?

I like main.rs after this tho. I like CommandHandle, get_fast_sync_hashes, BlockchainManagerHandle. not an in depth review but these things stood out to me in a once-over and some tangential reading to try and understand the changes

redsh4de · 2026-03-19T06:56:11Z

you should try and return something like Result<Self, NodeInitError> rather than panicking

Deferred this to the shutdown PRs - they depend on this branch so they carry everything over (https://github.com/Cuprate/cuprate/pull/585/changes#diff-d448bb1addb0153e0d62b48a7e6531f9988ea8f1846ab783540eaf9f2c87d87fR159)

I don't get the difference between or relative purposes of Node and NodeContext. Which should be used for what?

Node is meant to be the public facing API that the embedder receives and can interact with the node
NodeContext is meant to be the internal global context, replaces statics. Some things in each struct overlap but i prefer the granularity for the two seperate domains

Maybe there could be a better name for each struct so its self-documenting?

with dry_run_check calling std::process::exit(code), won't an embedder calling config.dry_run_check() get their process killed?

Yeah, good call

nit but SyncState renamed unnecessarily imo

It was a transitive change as i was also planning to add current sync target height to the struct, so the embedder can potentially create progress UIs/bars etc, got sidetracked though

there's no way to shut it down?

Ty, added shutdown function to #585 (https://github.com/Cuprate/cuprate/pull/585/changes#diff-d448bb1addb0153e0d62b48a7e6531f9988ea8f1846ab783540eaf9f2c87d87fR342-R344)

sneurlax · 2026-03-19T22:04:28Z

you should try and return something like Result<Self, NodeInitError> rather than panicking

Deferred this to the shutdown PRs - they depend on this branch so they carry everything over (https://github.com/Cuprate/cuprate/pull/585/changes#diff-d448bb1addb0153e0d62b48a7e6531f9988ea8f1846ab783540eaf9f2c87d87fR159)

I don't get the difference between or relative purposes of Node and NodeContext. Which should be used for what?

Node is meant to be the public facing API that the embedder receives and can interact with the node NodeContext is meant to be the internal global context, replaces statics. Some things in each struct overlap but i prefer the granularity for the two seperate domains

Maybe there could be a better name for each struct so its self-documenting?

with dry_run_check calling std::process::exit(code), won't an embedder calling config.dry_run_check() get their process killed?

Yeah, good call

nit but SyncState renamed unnecessarily imo

It was a transitive change as i was also planning to add current sync target height to the struct, so the embedder can potentially create progress UIs/bars etc, got sidetracked though

there's no way to shut it down?

Ty, added shutdown function to #585 (https://github.com/Cuprate/cuprate/pull/585/changes#diff-d448bb1addb0153e0d62b48a7e6531f9988ea8f1846ab783540eaf9f2c87d87fR342-R344)

Gotcha, OK :) sorry for the incomplete review then, glad to hear most of those issues are resolved by later PRs

binaries/cuprated/src/commands.rs

binaries/cuprated/src/config.rs

binaries/cuprated/src/blockchain/manager.rs

SyntheticBird45 · 2026-03-20T18:14:49Z

cancelling workflow because this is some doc nits, let's think a little about our carbon footprint.

…erHandle, doc nits

redsh4de · 2026-03-24T18:01:57Z

Think this is the last change i want to make here, didn't like how SyncNotify/State effectively functions as a handle without it being named such, reduces the mental load imo

Also added target_height to the handle so that embedders can create their own progress tracking items and whatnots

github-actions bot added the A-binaries Area: Related to binaries. label Mar 16, 2026

redsh4de marked this pull request as draft March 16, 2026 16:38

redsh4de marked this pull request as ready for review March 16, 2026 17:45

github-actions bot added the A-dependency Area: Related to dependencies, or changes to a Cargo.{toml,lock} file. label Mar 17, 2026

redsh4de force-pushed the feat/embeddable-cuprate branch from c680c1c to 6542272 Compare March 17, 2026 12:59

redsh4de mentioned this pull request Mar 17, 2026

cuprated: Add graceful shutdown #585

Open

redsh4de added 12 commits March 18, 2026 00:56

turn cuprated into a embeddable library

1da20d7

doc

4280b72

align with Cuprate#554 proposed API surface

b899c1c

clippy

abaa34c

add command input/output handling

3af399e

more readable API

8041778

add CommandHandler

d6a6da2

decouple config from CLI

253ce5b

move rayon init back to embedder

93b9c23

return result for config processing, move exit to main.rs

8b93be1

use actor pattern for commands, explicit lib/bin targets

c280090

init lazylock in both lib and main

2980076

redsh4de force-pushed the feat/embeddable-cuprate branch from bdbba2c to 81d85e1 Compare March 17, 2026 22:57

replace async loop with blocking thread for commands

618b162

redsh4de force-pushed the feat/embeddable-cuprate branch from 81d85e1 to 618b162 Compare March 18, 2026 03:38

remove mutable statics, add NodeContext for multi-instance support, docs

7c5e643

github-actions bot added the A-consensus Area: Related to consensus. label Mar 18, 2026

sneurlax reviewed Mar 19, 2026

View reviewed changes

SyntheticBird45 reviewed Mar 19, 2026

View reviewed changes

binaries/cuprated/src/commands.rs Outdated Show resolved Hide resolved

set command request channel capacity to 1 to match main

ecd44f5

SyntheticBird45 requested changes Mar 20, 2026

View reviewed changes

binaries/cuprated/src/config.rs Show resolved Hide resolved

binaries/cuprated/src/config.rs Outdated Show resolved Hide resolved

move pub use statement in config.rs

0939721

SyntheticBird45 reviewed Mar 20, 2026

View reviewed changes

binaries/cuprated/src/blockchain/manager.rs Outdated Show resolved Hide resolved

restore backticks for init_blockchain_manager doc comment

48e3cfc

redsh4de added 3 commits March 20, 2026 16:56

make dry_run_check pure, add DryRunResult

e65ea34

nuke the remaining statics

788f54c

replace SyncState with Syncer/SyncerHandle, add target_height to Sync…

1430d5d

…erHandle, doc nits

Conversation

redsh4de commented Mar 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Why

Where

How

Uh oh!

sneurlax Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

redsh4de Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

sneurlax Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

redsh4de Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

sneurlax Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

redsh4de Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

sneurlax Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

redsh4de Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

sneurlax commented Mar 19, 2026

Uh oh!

redsh4de commented Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sneurlax commented Mar 19, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

SyntheticBird45 commented Mar 20, 2026

Uh oh!

redsh4de commented Mar 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

redsh4de commented Mar 16, 2026 •

edited

Loading

sneurlax Mar 19, 2026 •

edited

Loading

redsh4de commented Mar 19, 2026 •

edited

Loading