From 99e2a83bd16338997c649395ba3de09e5e3bf5ef Mon Sep 17 00:00:00 2001 From: gusto Date: Thu, 12 Nov 2026 07:53:06 -0500 Subject: [PATCH] feat(module-backend): add the blockchain_module backend for the zone SDK --- .cargo-deny.toml | 1 + Cargo.lock | 35 +++++++ Cargo.toml | 3 +- README.md | 2 + module-backend/Cargo.toml | 22 +++++ module-backend/README.md | 17 ++++ module-backend/src/lib.rs | 199 ++++++++++++++++++++++++++++++++++++++ zone-sdk/src/lib.rs | 2 +- 8 files changed, 279 insertions(+), 2 deletions(-) create mode 100644 module-backend/Cargo.toml create mode 100644 module-backend/README.md create mode 100644 module-backend/src/lib.rs diff --git a/.cargo-deny.toml b/.cargo-deny.toml index 969093c..04117e4 100644 --- a/.cargo-deny.toml +++ b/.cargo-deny.toml @@ -61,6 +61,7 @@ allow-git = [ "https://github.com/EspressoSystems/jellyfish.git", "https://github.com/arkworks-rs/spongefish.git", "https://github.com/logos-blockchain/logos-blockchain-circuits.git", + "https://github.com/logos-blockchain/logos-blockchain-module.git", "https://github.com/logos-blockchain/logos-blockchain-rust-rapidsnark.git", "https://github.com/logos-blockchain/logos-blockchain-testing.git", "https://github.com/logos-blockchain/logos-blockchain.git", diff --git a/Cargo.lock b/Cargo.lock index ba06eeb..9828171 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -4158,6 +4158,20 @@ dependencies = [ "libc", ] +[[package]] +name = "logos-blockchain-client" +version = "0.0.999" +source = "git+https://github.com/logos-blockchain/logos-blockchain-module.git?rev=ac97b3293566b8df64ddcea95521a91b816862ae#ac97b3293566b8df64ddcea95521a91b816862ae" +dependencies = [ + "logos-blockchain-common-http-client", + "logos-blockchain-core", + "logos-blockchain-http-api-common", + "logos-rust-sdk", + "serde", + "serde_json", + "thiserror 2.0.21", +] + [[package]] name = "logos-blockchain-common-http-client" version = "0.0.0" @@ -5147,6 +5161,18 @@ dependencies = [ "tracing", ] +[[package]] +name = "logos-blockchain-zone-sdk-module-backend" +version = "0.0.0" +dependencies = [ + "async-trait", + "futures", + "logos-blockchain-client", + "logos-blockchain-zone-sdk", + "tokio", + "tracing", +] + [[package]] name = "logos-blockchain-zone-tests" version = "0.0.0" @@ -5169,6 +5195,15 @@ dependencies = [ "tracing", ] +[[package]] +name = "logos-rust-sdk" +version = "0.3.0" +source = "git+https://github.com/logos-co/logos-rust-sdk?rev=b572e8172ca512b41c102d555f00258b859629c0#b572e8172ca512b41c102d555f00258b859629c0" +dependencies = [ + "serde", + "serde_json", +] + [[package]] name = "logos-sql" version = "0.0.0" diff --git a/Cargo.toml b/Cargo.toml index be593d7..a7c8b63 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,5 +1,5 @@ [workspace] -members = ["logos_sql", "tests/logos-sql", "tests/zone-sdk", "zone-sdk"] +members = ["logos_sql", "module-backend", "tests/logos-sql", "tests/zone-sdk", "zone-sdk"] resolver = "2" [workspace.package] @@ -33,6 +33,7 @@ lb-testing-framework = { default-features = false, git = "https://gi lb-time = { default-features = false, git = "https://github.com/logos-blockchain/logos-blockchain.git", package = "logos-blockchain-time", rev = "a159f8c155df68d7e2f045a418ae737de246354e" } lb-utils = { default-features = false, git = "https://github.com/logos-blockchain/logos-blockchain.git", package = "logos-blockchain-utils", rev = "a159f8c155df68d7e2f045a418ae737de246354e" } lb-zone-sdk = { default-features = false, package = "logos-blockchain-zone-sdk", path = "zone-sdk" } +logos-blockchain-client = { default-features = false, git = "https://github.com/logos-blockchain/logos-blockchain-module.git", rev = "ac97b3293566b8df64ddcea95521a91b816862ae" } logos-blockchain-tests = { default-features = false, git = "https://github.com/logos-blockchain/logos-blockchain.git", rev = "a159f8c155df68d7e2f045a418ae737de246354e" } logos-blockchain-zone-tests = { default-features = false, path = "tests/zone-sdk" } logos-sql = { default-features = false, path = "logos_sql" } diff --git a/README.md b/README.md index b41b556..56ada7f 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,8 @@ This workspace contains: - `zone-sdk`: `logos-blockchain-zone-sdk`, for zone sequencers and readers. - `logos_sql`: `logos-sql`, SQLite replication built on the SDK. +- `module-backend`: `logos-blockchain-zone-sdk-module-backend`, the SDK's `adapter::Node` + over `blockchain_module` instead of the node's HTTP API. - `tests/zone-sdk` and `tests/logos-sql`: their Cucumber suites. ## Development diff --git a/module-backend/Cargo.toml b/module-backend/Cargo.toml new file mode 100644 index 0000000..da5701a --- /dev/null +++ b/module-backend/Cargo.toml @@ -0,0 +1,22 @@ +[package] +categories = { workspace = true } +description = "Zone SDK backend (adapter::Node) that talks to blockchain_module through logos-blockchain-client instead of HTTP" +edition = { workspace = true } +keywords = { workspace = true } +license = { workspace = true } +name = "logos-blockchain-zone-sdk-module-backend" +publish = false +readme = "README.md" +repository = { workspace = true } +version = { workspace = true } + +[lints] +workspace = true + +[dependencies] +async-trait = { workspace = true } +futures = { workspace = true } +lb-zone-sdk = { workspace = true } +logos-blockchain-client = { workspace = true } +tokio = { features = ["sync"], workspace = true } +tracing = { workspace = true } diff --git a/module-backend/README.md b/module-backend/README.md new file mode 100644 index 0000000..25a3e03 --- /dev/null +++ b/module-backend/README.md @@ -0,0 +1,17 @@ +# logos-blockchain-zone-sdk-module-backend + +Zone SDK `adapter::Node` backend that reads Bedrock through `blockchain_module` via +[`logos-blockchain-client`](https://github.com/logos-blockchain/logos-blockchain-module/tree/master/rust-client), a drop-in for `adapter::NodeHttpClient`: + +```rust +let node = NodeModuleClient::new(); // "blockchain_module" +let mut sequencer = ZoneSequencer::init(channel_id, signing_key, node, funding, None); +``` +Runs inside a Logos module loaded next to `blockchain_module`. + +`logos-blockchain-client` must pin the same node revision as this workspace, or the +node types on both sides of the backend are different types and it will not compile. +Bump the client pin in the root `Cargo.toml` together with the node revision. + +`limits()` returns an error: `blockchain_module` has no call for the node's limits +yet, so `ZoneSequencer::max_inscription_size` fails on this backend. diff --git a/module-backend/src/lib.rs b/module-backend/src/lib.rs new file mode 100644 index 0000000..49937c1 --- /dev/null +++ b/module-backend/src/lib.rs @@ -0,0 +1,199 @@ +use std::sync::Arc; + +use async_trait::async_trait; +use futures::stream; +use lb_zone_sdk::{ + adapter::{BoxStream, Node}, + node_types::{ + ApiBlock, BlockInfo, ChainServiceInfo, ChannelId, ChannelState, Error, Events, HeaderId, + LimitsResponseBody, ProcessedBlockEvent, SignedOps, Slot, StandardMode, TimeInfo, + Unverified, WalletFundRequestBody, WalletFundResponseBody, + }, +}; +use logos_blockchain_client::{ + BlockchainModuleClient, EventData, EventSubscription, LogosError, ModuleError, StreamItem, +}; +use tokio::sync::{mpsc, oneshot}; +use tracing::{debug, warn}; + +const TARGET: &str = "zone_sdk::module_backend"; +const STREAM_CAPACITY: usize = 64; + +type Callback = Box) + Send + 'static>; + +/// Holds only the module's name: binding a client is cheap, the Logos SDK +/// shares one connection per module name, so each call binds its own. +#[derive(Clone)] +pub struct NodeModuleClient { + module: Arc, +} + +impl Default for NodeModuleClient { + fn default() -> Self { + Self::new() + } +} + +impl NodeModuleClient { + #[must_use] + pub fn new() -> Self { + Self::bind("blockchain_module") + } + + #[must_use] + pub fn bind(module_name: &str) -> Self { + Self { + module: Arc::from(module_name), + } + } + + async fn call(&self, start: S) -> Result + where + T: Send + 'static, + S: FnOnce(&BlockchainModuleClient, Callback), + { + let (tx, rx) = oneshot::channel::>(); + start( + &BlockchainModuleClient::bind(&self.module), + Box::new(move |result| { + drop(tx.send(result)); + }), + ); + rx.await + .map_err(|_| Error::Client("module reply channel closed".to_owned()))? + .map_err(to_sdk_error) + } + + fn event_stream( + &self, + event: &'static str, + subscribe: Sub, + decode_item: Dec, + ) -> Result, Error> + where + T: Send + 'static, + Sub: FnOnce(&mut BlockchainModuleClient) -> Result, + Dec: Fn(&EventData) -> Result, ModuleError> + Send + 'static, + { + let mut client = BlockchainModuleClient::bind(&self.module); + let subscription = subscribe(&mut client) + .map_err(|e| Error::Client(format!("{event}: subscribe: {e}")))?; + + let (tx, rx) = mpsc::channel::(STREAM_CAPACITY); + std::thread::Builder::new() + .name(format!("zone-sdk-{event}")) + .spawn(move || { + // Ends, and unsubscribes, on the first event after the stream is + // dropped. + for ev in subscription { + match decode_item(&ev) { + Ok(StreamItem::Item(item)) => { + if tx.blocking_send(item).is_err() { + break; + } + } + Ok(StreamItem::End) => { + debug!(target: TARGET, event, "module ended the stream"); + break; + } + Err(e) => { + warn!(target: TARGET, event, error = %e, "undecodable event, skipping"); + } + } + } + }) + .map_err(|e| Error::Client(format!("{event}: spawn listener thread: {e}")))?; + + Ok(Box::pin(stream::unfold(rx, async |mut rx| { + rx.recv().await.map(|item| (item, rx)) + }))) + } +} + +#[expect( + clippy::needless_pass_by_value, + reason = "Used as a `map_err` function, which hands over the error by value." +)] +fn to_sdk_error(e: ModuleError) -> Error { + match e { + ModuleError::Transport { .. } => Error::Client(e.to_string()), + ModuleError::NodeNotRunning { .. } + | ModuleError::NotFound { .. } + | ModuleError::Module { .. } + | ModuleError::Decode { .. } => Error::Server(e.to_string()), + } +} + +#[async_trait] +impl Node for NodeModuleClient { + async fn consensus_info(&self) -> Result { + self.call(BlockchainModuleClient::cryptarchia_info_async) + .await + .map(|info| info.to_chain_service_info()) + } + + async fn time_info(&self) -> Result { + self.call(BlockchainModuleClient::time_info_async).await + } + + /// `blockchain_module` has no call for the node's limits yet: the node's C + /// bindings do not expose them. Everything else in the SDK works without + /// this; only `ZoneSequencer::max_inscription_size` reports the error. + async fn limits(&self) -> Result { + Err(Error::Server(format!( + "{}: limits are not exposed by the module", + self.module + ))) + } + + async fn channel_state(&self, channel_id: ChannelId) -> Result, Error> { + self.call(|c, cb| c.channel_state_async(channel_id, cb)) + .await + } + + async fn block_stream(&self) -> Result, Error> { + self.event_stream( + "processedBlock", + BlockchainModuleClient::on_processed_block, + BlockchainModuleClient::processed_block_item, + ) + } + + async fn lib_stream(&self) -> Result, Error> { + self.event_stream( + "libBlock", + BlockchainModuleClient::on_lib_block, + BlockchainModuleClient::lib_block_item, + ) + } + + async fn block(&self, id: HeaderId) -> Result, Error> { + self.call(|c, cb| c.block_async(id, cb)).await + } + + async fn block_events(&self, id: HeaderId) -> Result, Error> { + self.call(|c, cb| c.block_events_async(id, cb)).await + } + + async fn immutable_blocks( + &self, + slot_from: Slot, + slot_to: Slot, + ) -> Result, Error> { + self.call(|c, cb| c.blocks_async(slot_from, slot_to, cb)) + .await + } + + async fn post_transaction(&self, tx: SignedOps) -> Result<(), Error> { + self.call(|c, cb| c.submit_transaction_async(&tx, cb)) + .await + .map(|_hash| ()) + } + + async fn fund_tx( + &self, + request: WalletFundRequestBody, + ) -> Result { + self.call(|c, cb| c.fund_tx_async(&request, cb)).await + } +} diff --git a/zone-sdk/src/lib.rs b/zone-sdk/src/lib.rs index 1c9a8db..4da52d0 100644 --- a/zone-sdk/src/lib.rs +++ b/zone-sdk/src/lib.rs @@ -111,7 +111,7 @@ pub mod node_types { mantle::{ SignedOps, TxHash, Value, channel::ChannelState, - ledger::Inputs, + ledger::{Inputs, verification_mode::StandardMode}, ops::channel::{ChannelId, MsgId, deposit::Metadata, inscribe::Inscription}, transactions::states::Unverified, },