fuel-streams-domains

Fuel Streams Domains

Domain models and database infrastructure for the Fuel Data Systems project

📚 Documentation   🐛 Report Bug   ✨ Request Feature

📝 About The Project

Fuel Streams Domains provides the core domain models and database infrastructure for the Fuel Data Systems project. It defines the data structures, repositories, and database schema for all blockchain entities, enabling efficient storage, retrieval, and manipulation of blockchain data.

[!NOTE] This crate is specifically modeled for the Fuel Data Systems project, and is not intended for general use outside of the project.

🏗️ Architecture

The crate is organized around domain-driven design principles, with each blockchain entity (blocks, transactions, etc.) represented as a separate domain module. Each domain module contains:

• Types: Core data structures representing the domain entity
• Repository: Database access layer for the domain entity
• DB Item: Database representation of the entity
• Query Parameters: Structured query parameters for filtering entities
• Subjects: Message subjects for pub/sub communication
• Packets: Serialization formats for network communication

The infra module provides shared infrastructure components:

• DB: Database connection and transaction management
• Record: Common record handling functionality
• Repository: Base repository patterns and traits

📊 Domain Entities

The following domain entities are supported:

• Blocks: Blockchain blocks with headers and metadata
• Transactions: Blockchain transactions
• Inputs: Transaction inputs
• Outputs: Transaction outputs
• Messages: Cross-chain messages
• Receipts: Transaction execution receipts
• UTXOs: Unspent transaction outputs
• Predicates: Smart contract predicates

🗃️ Database Schema

The crate includes SQL migrations for creating and managing the database schema. These migrations define tables for each domain entity and establish relationships between them.

🛠️ Usage

Add this dependency to your Cargo.toml:

[dependencies]
fuel-streams-domains = "*"

Working with Database Connection

use std::sync::Arc;
use fuel_streams_domains::infra::{Db, DbConnectionOpts};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a database connection
    let db_opts = DbConnectionOpts::default();
    let db = Db::new(db_opts).await?;

    // Use the database connection
    // ...

    Ok(())
}

Finding Blocks

use std::sync::Arc;
use fuel_streams_domains::{
    blocks::{Block, BlocksQuery},
    infra::{Db, DbConnectionOpts, QueryOptions, Repository},
};
use fuel_streams_types::BlockHeight;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a database connection
    let db_opts = DbConnectionOpts::default();
    let db = Db::new(db_opts).await?;

    // Find the last block height
    let options = QueryOptions::default();
    let last_height = Block::find_last_block_height(&db, &options).await?;
    println!("Last block height: {}", last_height);

    // Find blocks in a specific height range
    let start_height = BlockHeight::from(100);
    let end_height = BlockHeight::from(200);
    let blocks = Block::find_in_height_range(&db.pool, start_height, end_height, &options).await?;
    println!("Found {} blocks in range", blocks.len());

    Ok(())
}

Working with Transactions

use std::sync::Arc;
use fuel_streams_domains::{
    blocks::Block,
    infra::{Db, DbConnectionOpts, Repository},
};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a database connection
    let db_opts = DbConnectionOpts::default();
    let db = Db::new(db_opts).await?;

    // Create a block (simplified example)
    let block = Block::default();

    // Get transactions for a block
    let transactions = block.transactions_from_block(&db.pool).await?;
    println!("Block has {} transactions", transactions.len());

    Ok(())
}

Finding Blocks with Transactions

use std::sync::Arc;
use fuel_streams_domains::{
    blocks::Block,
    infra::{Db, DbConnectionOpts, QueryOptions, Repository},
};
use fuel_streams_types::BlockHeight;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a database connection
    let db_opts = DbConnectionOpts::default();
    let db = Db::new(db_opts).await?;

    // Find blocks with their transactions in a specific height range
    let options = QueryOptions::default();
    let start_height = BlockHeight::from(100);
    let end_height = BlockHeight::from(110);

    let blocks_with_txs = Block::find_blocks_with_transactions(
        &db.pool,
        start_height,
        end_height,
        &options
    ).await?;

    // Process blocks and their transactions
    for (block, transactions) in blocks_with_txs {
        println!("Block #{} has {} transactions", block.block_height, transactions.len());
    }

    Ok(())
}

🧪 Testing

The crate provides mock implementations of domain entities for testing purposes:

use fuel_streams_domains::mocks::*;

#[test]
fn test_with_mock_data() {
    let mock_block = MockBlock::default();
    let mock_tx = MockTransaction::default();

    // Use mock data for testing
    assert_eq!(mock_block.height.value(), 0);
}

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

For more information on contributing, please see the CONTRIBUTING.md file in the root of the repository.

📜 License

This repo is licensed under the Apache-2.0 license. See LICENSE for more information.