feat: improve chainhook-sdk interface

[MicaiahReid]

Description

The goal of this PR is to make it much easier to use the Chainhook SDK. Previously, there were many fields that are rarely needed for the average user which had to be set when configuring the SDK. Many of these fields had confusing names that made it difficult to know how they were used in the SDK. Additionally, many of these fields were only needed for observing stacks events, but bitcoin-only users had to specify them anyways.

This has a few major changes to the Chainhook SDK:

• Removing some unused fields from the event observer config (cache_path, data_handler_tx, andingestion_port) (694fb4d)
• Renames display_logs -> display_stacks_ingestion_logs (694fb4d)
• Renames EventObserverConfigOverrides -> StacksEventObserverConfigBuilder (9da1178)
• Renames ingestion_port -> chainhook_stacks_block_ingestion_port for StacksEventObserverConfigBuilder (4e997fc)
• Adds a BitcoinEventObserverConfigBuilder (fc67dff)
• Renames some very confusingly named structs (5a4cb39):
  • *ChainhookFullSpecification => *ChainhookSpecificationNetworkMap
  • *ChainhookNetworkSpecification => *ChainhookSpecification
  • *ChainhookSpecification => *ChainhookInstance
• refactor: moves stacks/bitcoin specific types to their respective types folder (83e8336)
• adds helpers for registering chainhooks (4debc28)
• renames ChainhookConfig -> ChainhookStore (c54b6e7)
• add EventObserverBuilder to make a clean interface for starting an event observer (fe04dd9)
• add a bunch of rsdoc comments with examples

Breaking change?

This will break some aspects of the Chainhook SDK. It should be a simple upgrade:

• If you're building any of the above structs directly, rename the fields accordingly
• If you're using ::new(..) to build any of the above structs with fields that are removed, you may need to remove some fields
• You can probably remove a good bit of code by using the builders

Example

New code example to start a bitcoin event observer:

fn start_observer(ctx: &Context) -> Result<(), String> {
    let json_predicate = std::fs::read_to_string("./predicate.json").expect("Unable to read file");

    let hook_instance: BitcoinChainhookInstance =
        serde_json::from_str(&json_predicate).expect("unable to parse chainhook spec");

    let config = BitcoinEventObserverConfigBuilder::new()
        .rpc_username("regtest")
        .rpc_password("test1235")
        .rpc_url("http://0.0.0.0:8332")
        .finish()?
        .register_bitcoin_chainhook_instance(hook_instance)?
        .to_owned();

    let (observer_commands_tx, observer_commands_rx) = channel();

    EventObserverBuilder::new(config, &observer_commands_tx, observer_commands_rx, &ctx)
        .start()
        .map_err(|e| format!("event observer error: {}", e.to_string()))
}

Previous usage of starting a bitcoin observer

    let json_predicate = std::fs::read_to_string("./predicate.json").expect("Unable to read file");

    let hook_spec: BitcoinChainhookFullSpecification =
        serde_json::from_str(&json_predicate).expect("unable to parse chainhook spec");

    let bitcoin_network = BitcoinNetwork::Regtest;
    let stacks_network = chainhook_sdk::types::StacksNetwork::Mainnet;
    let mut bitcoin_hook_spec = hook_spec
        .into_selected_network_specification(&bitcoin_network)
        .expect("unable to parse bitcoin spec");
    bitcoin_hook_spec.enabled = true;

    let mut chainhook_config = ChainhookConfig::new();
    chainhook_config
        .register_specification(ChainhookSpecification::Bitcoin(bitcoin_hook_spec))
        .expect("failed to register chainhook spec");

    let config = EventObserverConfig {
        chainhook_config: Some(chainhook_config),
        bitcoin_rpc_proxy_enabled: false,
        ingestion_port: 0,
        bitcoind_rpc_username: "regtest".to_string(),
        bitcoind_rpc_password: "test1235".to_string(),
        bitcoind_rpc_url: "http://0.0.0.0:8332".to_string(),
        bitcoin_block_signaling: BitcoinBlockSignaling::ZeroMQ("tcp://0.0.0.0:18543".to_string()),
        display_logs: true,
        cache_path: String::new(),
        bitcoin_network: bitcoin_network,
        stacks_network: stacks_network,
        data_handler_tx: None,
        prometheus_monitoring_port: None,
    };
    let (observer_commands_tx, observer_commands_rx) = channel();

    // set up context to configure how we display logs from the event observer
    let logger = hiro_system_kit::log::setup_logger();
    let _guard = hiro_system_kit::log::setup_global_logger(logger.clone());
    let ctx = chainhook_sdk::utils::Context {
        logger: Some(logger),
        tracer: false,
    };

    let moved_ctx = ctx.clone();
    let _ = hiro_system_kit::thread_named("Chainhook event observer")
        .spawn(move || {
            let future = start_bitcoin_event_observer(
                config,
                observer_commands_tx,
                observer_commands_rx,
                None,
                None,
                moved_ctx,
            );
            match hiro_system_kit::nestable_block_on(future) {
                Ok(_) => {}
                Err(e) => {
                    println!("{}", e)
                }
            }
        })
        .expect("unable to spawn thread");

Fixes #598

[csgui]

Is there any reason in the codebase to truncate 4 bytes (chars) to 1 byte (u8)? Consider using a byte literal b'[', for instance, for those ASCII characters.

[csgui]

@MicaiahReid I should have provided more information from the start, sorry.

Using a byte literal clarifies the code's intent: only ASCII characters are allowed for StacksOpcodes. Any non-ASCII character, like ∞, will be rejected. Casting types allows to truncate NON-ASCII chars like '∞' as u8.

Other thing I am considering in this case is the runtime performance. StacksOpcodes is used by the indexer, inside a loop. The overhead of casting '[' as u8 involves a runtime operation to convert the char to u8. This is not a super-heavy operation but is being performed inside a loop in a performance-critical section, thus the difference might become more noticeable.

I'm unsure of the exact impact on the indexer's performance, but any code involving it should consider performance optimization, in my opinion (maybe I'm getting a bit too performance-obsessed lately, thanks to working on Clarity-Wasm... 😛 ).

[MicaiahReid]

@csgui Thanks for the explanation! I've applied your suggestion.

[csgui]

The overall refactoring implemented in this PR looks good. Just left some comments to be addressed.

[MicaiahReid]

The overall refactoring implemented in this PR looks good. Just left some comments to be addressed.

@csgui, I'm not quite following you on this one - what's the difference between '[' as u8 and b'['?

[csgui]

The overall refactoring implemented in this PR looks good. Just left some comments to be addressed.

@csgui, I'm not quite following you on this one - what's the difference between '[' as u8 and b'['?

Added more context on the comment.

[smcclellan]

Can we merge this @MicaiahReid?