matroskin 0.1.0

matroskin is an asynchronous Rust client for WhatsMiner ASIC hardware. An internal actor state machine encapsulates the WhatsMiner v3 TCP protocol—handling framing, encrypted authentication, and automatic reconnects behind a lock-free, strongly-typed actor.send(cmd) interface.

[!WARNING] Operational & API Version Status:

• API Version: The library implements WhatsMiner API v3.0.3. The upstream API has since released v3.0.5; features introduced in 3.0.4/3.0.5 are not yet supported.
• Hardware Validation: Read-only queries (get.*) and verified control commands (set.miner.fastboot, set.system.reboot, set.user.permission) have been tested on physical hardware (marked ●). All other state-modifying operations (marked ○) are verified against the mock harness and must be evaluated with caution prior to production use.

Highlights

• Actor-based FSM: Single-owner Tokio task manages the connection lifecycle without mutexes or runtime locks.
• Complete API Coverage: All 39 WhatsMiner v3 commands implemented as typed, owned structures.
• Simple Command Dispatch: Uniform actor.send(cmd).await? interface with strongly-typed request and response payloads.
• Resilient Reconnection: Transparent backoff and reconnect queuing that preserves pending commands during connection drops.
• Secure by Default: Zeroizing credentials and session salts on drop, AES-256-ECB parameter encryption, and automatic secret redaction in debug logs.

Quickstart

Add matroskin and tokio to your Cargo.toml (requires Rust 1.85+ / Edition 2024):

[dependencies]
matroskin = "0.1.0"
tokio = { version = "1", features = ["full"] }

Basic Usage

Note: Initializing an Actor via Actor::new requires an active Tokio runtime context. Actor::clone() creates an independent actor instance; wrap in Arc<Actor> to share one connected actor across tasks.

use matroskin::{
    account::Account,
    actor::Actor,
    command::get_device_info::GetDeviceInfo,
    password::Password,
};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Initialize actor in `Created` state (synchronous in memory, no network I/O yet).
    let actor = Actor::new("10.10.10.10:4433", Account::Super, Password::Super);

    // 2. Queue non-blocking connect intent.
    actor.connect()?;

    // 3. Send an owned command by value.
    // The command mailbox waits until the actor establishes a Connected session.
    let response = actor.send(GetDeviceInfo::all()).await?;
    println!("Device info: {:#?}", response.msg);

    // 4. Graceful non-blocking shutdown intent.
    actor.shutdown()?;
    Ok(())
}

Flat Commands & Typed Parameters

All commands use flat structures with named fields and .new(...) constructors. Executing actor.send(cmd) returns Response<C::Response>, where C::Response is the typed payload in .msg:

use matroskin::{
    account::{Account, Users},
    actor::Actor,
    command::{
        get_device_info::GetDeviceInfo,
        set_miner_pools::{PoolConfig, SetMinerPools},
        set_user_permission::SetUserPermission,
    },
    password::Password,
};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let actor = Actor::new("10.10.10.10:4433", Account::Super, Password::Super);
    actor.connect()?;

    // Query device info: response payload is DeviceInfo (optional salt is redacted)
    let info = actor.send(GetDeviceInfo::all()).await?;
    println!("Salt present: {}", info.msg.salt.is_some());

    // Set user permissions: requires All permission level
    let perm = SetUserPermission::new(Users::User1, "set.system.led,set.miner.pools");
    actor.send(perm).await?;

    // Configure pools: 3 fixed entries with protected credentials (AES-256-ECB encrypted)
    let pools = [
        PoolConfig::new("stratum+tcp://pool1.com:3333", "worker1", "pass1"),
        PoolConfig::new("stratum+tcp://pool2.com:3333", "worker2", "pass2"),
        PoolConfig::new("stratum+tcp://pool3.com:3333", "worker3", "pass3"),
    ];
    actor.send(SetMinerPools::new(pools)).await?;

    actor.shutdown()?;
    Ok(())
}

Direct Streaming Operations

Streaming operations take exclusive ownership of the network transport while active:

use matroskin::{account::Account, actor::Actor, password::Password};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let actor = Actor::new("10.10.10.10:4433", Account::Super, Password::Super);
    actor.connect()?;

    // Download system logs directly into an owned AsyncWrite destination
    let log_file = tokio::fs::File::create("miner.log").await?;
    actor.download_log(log_file).await?;

    // Firmware upload accepts an owned AsyncRead source and exact byte length
    // (Use with caution on production devices)
    // let fw_file = tokio::fs::File::open("firmware.bin").await?;
    // let len = fw_file.metadata().await?.len();
    // actor.upload_firmware(fw_file, len).await?;

    actor.shutdown()?;
    Ok(())
}

Command Inventory

Status of implemented commands against the WhatsMiner API v3 (target specification: v3.0.3, current upstream: v3.0.5):

• ● Hardware verified: Tested and confirmed on physical WhatsMiner hardware.
• ○ Mock verified: Verified against the in-process mock test suite; use on physical hardware at your own risk.

Development & Testing

The repository provides built-in Cargo aliases in .cargo/config.toml:

# Run all unit tests, mock device tests, and doc tests
cargo test

# Run in-process mock device tests (thread-isolated)
cargo test-mock

# Strict linter check across all targets and features
cargo lint

# Check code formatting
cargo fmt-check

# Verify documentation builds without warnings
cargo doc-check

# List hardware integration tests without connecting to an ASIC
cargo test-real-list

# Run physical hardware tests (requires ASIC reachable at MINER_ADDR)
MINER_ADDR=10.20.1.2:4433 cargo test --test real_device --features real-device

• See mock device testing for in-process mock device testing.
• See physical hardware testing for real-device testing guidelines.
• See architecture reference for the actor, session, and protocol model.
• See AGENTS.md for repository terminology and contribution constraints.

License

Dual-licensed under either of:

• MIT license
• Apache License, Version 2.0

at your option.