Layer2 Async API Documentation¶

Date: June 22, 2025

Status (June 2025): The Layer2 async API and related modules are under active development. The implementation is not yet production-ready. Some features described below may not work as intended due to unresolved build and logic errors, especially in Layer2Manager and HSM/security modules. See ROADMAP.md for up-to-date status and actionable items.

Known Issues:

• Critical errors remain in Layer2Manager and HSM/security modules; many async methods may fail or be incomplete.
• Not all tests pass; do not rely on this API for production use.
• Documentation and code are being actively aligned—expect breaking changes.
• For details, see the main ROADMAP.md.

This document provides a comprehensive reference for the asynchronous API of the Layer2 modules in Anya-core.

Layer2Manager Async API¶

The Layer2Manager is the central interface for working with Layer2 protocols. It provides methods to initialize protocols and access their functionality.

Initialization¶

/// Initialize all Layer2 protocols asynchronously
pub async fn initialize_all_async(&self) -> Result<(), Layer2Error>

Example usage:

let layer2_manager = Layer2Manager::new();
layer2_manager.initialize_all_async().await?;

Protocol Access¶

/// Get a Layer2 protocol implementation by type asynchronously
pub async fn get_protocol_async(&self, protocol_type: Layer2ProtocolType) 
    -> Result<Box<dyn Layer2ProtocolAsync + Send + Sync>, Layer2Error>

Example usage:

let bob_protocol = layer2_manager.get_protocol_async(Layer2ProtocolType::Bob).await?;

Cross-Layer Operations¶

/// Perform cross-layer asset transfer asynchronously
pub async fn cross_layer_transfer_async(
    &self,
    asset_id: &AssetId,
    amount: u64,
    source_protocol: Layer2ProtocolType,
    destination_protocol: Layer2ProtocolType,
) -> Result<TransferProof, Layer2Error>

/// Verify cross-layer transfer proof asynchronously
pub async fn verify_cross_layer_proof_async(
    &self,
    proof: &TransferProof,
) -> Result<bool, Layer2Error>

Example usage:

let proof = layer2_manager.cross_layer_transfer_async(
    &asset_id,
    100_000,
    Layer2ProtocolType::Bob,
    Layer2ProtocolType::Lightning,
).await?;

let is_valid = layer2_manager.verify_cross_layer_proof_async(&proof).await?;

Layer2ProtocolAsync Trait¶

The Layer2ProtocolAsync trait defines the interface for async operations on Layer2 protocols.

#[async_trait]
pub trait Layer2ProtocolAsync {
    /// Initialize the protocol asynchronously
    async fn initialize_async(&self) -> Result<(), Layer2Error>;

    /// Submit transaction to the Layer2 protocol asynchronously
    async fn submit_transaction_async(&self, transaction: &Transaction) -> Result<TxStatus, Layer2Error>;

    /// Get transaction status asynchronously
    async fn get_transaction_status_async(&self, tx_id: &TxId) -> Result<TxStatus, Layer2Error>;

    /// Transfer asset on the Layer2 protocol asynchronously
    async fn transfer_asset_async(
        &self,
        asset_id: &AssetId,
        amount: u64,
        recipient: &Address,
    ) -> Result<TxId, Layer2Error>;

    /// Verify proof on the Layer2 protocol asynchronously
    async fn verify_proof_async(&self, proof: &Proof) -> Result<bool, Layer2Error>;
}

Protocol-Specific Implementations¶

Each Layer2 protocol implements the Layer2ProtocolAsync trait with protocol-specific functionality.

BobClient¶

#[async_trait]
impl Layer2ProtocolAsync for BobClient {
    async fn initialize_async(&self) -> Result<(), Layer2Error> {
        // Implementation details
    }

    async fn submit_transaction_async(&self, transaction: &Transaction) -> Result<TxStatus, Layer2Error> {
        // Implementation details
    }

    // Other methods implemented...
}

LightningNetwork¶

#[async_trait]
impl Layer2ProtocolAsync for LightningNetwork {
    async fn initialize_async(&self) -> Result<(), Layer2Error> {
        // Implementation details
    }

    async fn transfer_asset_async(
        &self,
        asset_id: &AssetId,
        amount: u64,
        recipient: &Address,
    ) -> Result<TxId, Layer2Error> {
        // LN-specific implementation for transferring assets
    }

    // Other methods implemented...
}

Error Handling¶

All async methods return a Result with Layer2Error for error handling. Error types specific to async operations include:

pub enum Layer2Error {
    // Existing error types...

    /// Error indicating an async operation timeout
    AsyncTimeout(String),

    /// Error indicating an async runtime error
    AsyncRuntimeError(String),

    /// Error indicating a task cancellation
    TaskCancelled(String),
}

Advanced Usage Patterns¶

Concurrent Operations¶

use futures::future::join_all;

async fn process_transactions(txs: Vec<Transaction>) -> Vec<Result<TxStatus, Layer2Error>> {
    let layer2_manager = Layer2Manager::new();
    layer2_manager.initialize_all_async().await?;

    let protocol = layer2_manager.get_protocol_async(Layer2ProtocolType::Bob).await?;

    let futures = txs.iter()
        .map(|tx| protocol.submit_transaction_async(tx))
        .collect::<Vec<_>>();

    join_all(futures).await
}

Timeout Handling¶

use tokio::time::{timeout, Duration};

async fn submit_with_timeout(
    protocol: &dyn Layer2ProtocolAsync,
    tx: &Transaction,
    timeout_duration: Duration,
) -> Result<TxStatus, Layer2Error> {
    timeout(timeout_duration, protocol.submit_transaction_async(tx))
        .await
        .map_err(|_| Layer2Error::AsyncTimeout("Transaction submission timed out".into()))?
}

Cancellation Handling¶

use tokio::select;
use tokio::sync::oneshot;

async fn cancellable_transfer(
    protocol: &dyn Layer2ProtocolAsync,
    asset_id: &AssetId,
    amount: u64,
    recipient: &Address,
    cancel_rx: oneshot::Receiver<()>,
) -> Result<TxId, Layer2Error> {
    select! {
        result = protocol.transfer_asset_async(asset_id, amount, recipient) => result,
        _ = cancel_rx => Err(Layer2Error::TaskCancelled("Transfer was cancelled".into())),
    }
}

Configuration¶

Async operations can be configured through the Layer2Config struct:

pub struct Layer2Config {
    // Existing fields...

    /// Maximum number of concurrent operations
    pub max_concurrency: usize,

    /// Default timeout for async operations in milliseconds
    pub default_timeout_ms: u64,

    /// Connection pool settings
    pub connection_pool: ConnectionPoolConfig,
}

Testing¶

Use the testing utilities provided for testing async implementations:

#[tokio::test]
async fn test_bob_transfer() {
    let mock_protocol = MockLayer2Protocol::new();
    // Set up expectations

    let result = mock_protocol.transfer_asset_async(&asset_id, 100, &address).await;
    // Assert expectations
}

Compatibility¶

The async API is designed to work alongside the existing synchronous API. For code that cannot be migrated to async, synchronous wrappers are provided:

// Using async code in sync context (blocks the current thread)
fn submit_transaction_sync(&self, tx: &Transaction) -> Result<TxStatus, Layer2Error> {
    tokio::runtime::Handle::current().block_on(async {
        self.submit_transaction_async(tx).await
    })
}

For detailed migration guidance, please see the Sync to Async Migration Guide.