Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
1 change: 1 addition & 0 deletions .cargo-deny.toml
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,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",
Expand Down
35 changes: 35 additions & 0 deletions Cargo.lock

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

3 changes: 2 additions & 1 deletion Cargo.toml
Original file line number Diff line number Diff line change
@@ -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]
Expand Down Expand Up @@ -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" }
Expand Down
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
22 changes: 22 additions & 0 deletions module-backend/Cargo.toml
Original file line number Diff line number Diff line change
@@ -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 }
17 changes: 17 additions & 0 deletions module-backend/README.md
Original file line number Diff line number Diff line change
@@ -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.
199 changes: 199 additions & 0 deletions module-backend/src/lib.rs
Original file line number Diff line number Diff line change
@@ -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<T> = Box<dyn FnOnce(Result<T, ModuleError>) + 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<str>,
}

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<T, S>(&self, start: S) -> Result<T, Error>
where
T: Send + 'static,
S: FnOnce(&BlockchainModuleClient, Callback<T>),
{
let (tx, rx) = oneshot::channel::<Result<T, ModuleError>>();
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<T, Sub, Dec>(
&self,
event: &'static str,
subscribe: Sub,
decode_item: Dec,
) -> Result<BoxStream<T>, Error>
where
T: Send + 'static,
Sub: FnOnce(&mut BlockchainModuleClient) -> Result<EventSubscription, LogosError>,
Dec: Fn(&EventData) -> Result<StreamItem<T>, 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::<T>(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<ChainServiceInfo, Error> {
self.call(BlockchainModuleClient::cryptarchia_info_async)
.await
.map(|info| info.to_chain_service_info())
}

async fn time_info(&self) -> Result<TimeInfo, Error> {
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<LimitsResponseBody, Error> {
Err(Error::Server(format!(
"{}: limits are not exposed by the module",
self.module
)))
}

async fn channel_state(&self, channel_id: ChannelId) -> Result<Option<ChannelState>, Error> {
self.call(|c, cb| c.channel_state_async(channel_id, cb))
.await
}

async fn block_stream(&self) -> Result<BoxStream<ProcessedBlockEvent>, Error> {
self.event_stream(
"processedBlock",
BlockchainModuleClient::on_processed_block,
BlockchainModuleClient::processed_block_item,
)
}

async fn lib_stream(&self) -> Result<BoxStream<BlockInfo>, Error> {
self.event_stream(
"libBlock",
BlockchainModuleClient::on_lib_block,
BlockchainModuleClient::lib_block_item,
)
}

async fn block(&self, id: HeaderId) -> Result<Option<ApiBlock>, Error> {
self.call(|c, cb| c.block_async(id, cb)).await
}

async fn block_events(&self, id: HeaderId) -> Result<Option<Events>, Error> {
self.call(|c, cb| c.block_events_async(id, cb)).await
}

async fn immutable_blocks(
&self,
slot_from: Slot,
slot_to: Slot,
) -> Result<Vec<ApiBlock>, Error> {
self.call(|c, cb| c.blocks_async(slot_from, slot_to, cb))
.await
}

async fn post_transaction(&self, tx: SignedOps<Unverified, StandardMode>) -> Result<(), Error> {
self.call(|c, cb| c.submit_transaction_async(&tx, cb))
.await
.map(|_hash| ())
}

async fn fund_tx(
&self,
request: WalletFundRequestBody,
) -> Result<WalletFundResponseBody, Error> {
self.call(|c, cb| c.fund_tx_async(&request, cb)).await
}
}
2 changes: 1 addition & 1 deletion zone-sdk/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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,
},
Expand Down
Loading