diff --git a/bee-inx/examples/utxo.rs b/bee-inx/examples/utxo.rs index 46947b4d8..3f2c4529e 100644 --- a/bee-inx/examples/utxo.rs +++ b/bee-inx/examples/utxo.rs @@ -15,7 +15,7 @@ async fn main() -> Result<(), Error> { let mut unspent_outputs = inx.read_unspent_outputs().await?; let mut count = 0; - while let Some(_) = unspent_outputs.next().await { + while let Some(_unspent_output) = unspent_outputs.next().await { count += 1; } println!("Read {count} unspent outputs."); diff --git a/bee-inx/src/block/mod.rs b/bee-inx/src/block/mod.rs index 0b5afa26a..06d1093be 100644 --- a/bee-inx/src/block/mod.rs +++ b/bee-inx/src/block/mod.rs @@ -1,6 +1,7 @@ // Copyright 2022 IOTA Stiftung // SPDX-License-Identifier: Apache-2.0 +/// A module that provides block related INX responses. pub mod responses; use futures::stream::{Stream, StreamExt}; @@ -15,7 +16,7 @@ use crate::{ }; impl Inx { - // TODO + /// Listens to all blocks. pub async fn listen_to_blocks(&mut self) -> Result>, Error> { Ok(self .client @@ -25,7 +26,7 @@ impl Inx { .map(try_from_inx_type)) } - // TODO + /// Listens to solid blocks. pub async fn listen_to_solid_blocks(&mut self) -> Result>, Error> { Ok(self .client @@ -35,7 +36,7 @@ impl Inx { .map(try_from_inx_type)) } - // TODO + /// Listens to referenced blocks. pub async fn listen_to_referenced_blocks( &mut self, ) -> Result>, Error> { @@ -47,7 +48,7 @@ impl Inx { .map(try_from_inx_type)) } - // TODO + /// Requests the block with the given block id. pub async fn read_block(&mut self, block_id: bee::BlockId) -> Result, Error> { Ok(self .client @@ -58,7 +59,7 @@ impl Inx { .into()) } - // TODO + /// Requests the metadata of the block with the given block id. pub async fn read_block_metadata(&mut self, block_id: bee::BlockId) -> Result { Ok(self .client @@ -68,7 +69,7 @@ impl Inx { .try_into()?) } - // TODO + /// Submits a block and returns its corresponding block id. pub async fn submit_block(&mut self, raw_block: Raw) -> Result { Ok(self .client diff --git a/bee-inx/src/block/responses.rs b/bee-inx/src/block/responses.rs index f98f38883..3f96bdf9e 100644 --- a/bee-inx/src/block/responses.rs +++ b/bee-inx/src/block/responses.rs @@ -153,6 +153,7 @@ impl From for inx::LedgerInclusionState { } } +/// Whether a block contains a transaction that is either included or conflicting, or contains no transaction at all. #[allow(missing_docs)] #[derive(Clone, Debug, PartialEq, Eq)] pub enum LedgerInclusionState { diff --git a/bee-inx/src/error.rs b/bee-inx/src/error.rs index 152ef62e5..1094a9530 100644 --- a/bee-inx/src/error.rs +++ b/bee-inx/src/error.rs @@ -4,6 +4,7 @@ use inx::tonic; use thiserror::Error; +#[allow(missing_docs)] #[derive(Debug, Error)] pub enum Error { #[error(transparent)] diff --git a/bee-inx/src/lib.rs b/bee-inx/src/lib.rs index 6612111fd..a3c9f40f3 100644 --- a/bee-inx/src/lib.rs +++ b/bee-inx/src/lib.rs @@ -1,18 +1,28 @@ // Copyright 2022 IOTA Stiftung // SPDX-License-Identifier: Apache-2.0 +//! Bee compatible INX types and INX node request bindings. + +#![deny(missing_docs)] + mod error; +/// A module that provides block related requests.. pub mod block; +/// A module that provides the INX client. pub mod client; +/// A module that provides milestone related requests. pub mod milestone; +/// A module that provides node related requests. pub mod node; +/// A module that provides the [`Raw`] struct. pub mod raw; +/// A module that provides UTXO ledger related requests. pub mod utxo; pub use self::{block::*, error::Error, milestone::*, node::*, raw::*, utxo::*}; -pub mod inx { +pub(crate) mod inx { pub use ::inx::proto::{ block_metadata::*, ledger_update::{marker::*, *}, @@ -36,6 +46,7 @@ pub(crate) mod bee { pub use bee_block::{protocol::protocol_parameters, rand::output::rand_output}; } +#[allow(missing_docs)] #[macro_export] macro_rules! return_err_if_none { ($object:ident.$field:ident) => { diff --git a/bee-inx/src/milestone/mod.rs b/bee-inx/src/milestone/mod.rs index 314bd89f3..59693fe24 100644 --- a/bee-inx/src/milestone/mod.rs +++ b/bee-inx/src/milestone/mod.rs @@ -1,7 +1,9 @@ // Copyright 2022 IOTA Stiftung // SPDX-License-Identifier: Apache-2.0 +/// A module that provides milestone related INX requests. pub mod requests; +/// A module that provides milestone related INX responses. pub mod responses; use futures::stream::{Stream, StreamExt}; @@ -15,7 +17,7 @@ use crate::{ }; impl Inx { - /// TODO + /// Requests a particular milestone. pub async fn read_milestone(&mut self, request: MilestoneRequest) -> Result { Ok(self .client @@ -48,7 +50,7 @@ impl Inx { .map(try_from_inx_type)) } - /// TODO + /// Requests "white flag" data for a milestone. pub async fn compute_white_flag(&mut self, request: WhiteFlagRequest) -> Result { Ok(self .client @@ -71,7 +73,7 @@ impl Inx { .map(try_from_inx_type)) } - /// TODO + /// Reads the past cone metadata of a milestone specified by a [`MilestoneRequest`]. pub async fn read_milestone_cone_metadata( &mut self, request: MilestoneRequest, diff --git a/bee-inx/src/milestone/requests.rs b/bee-inx/src/milestone/requests.rs index 957433167..aae957233 100644 --- a/bee-inx/src/milestone/requests.rs +++ b/bee-inx/src/milestone/requests.rs @@ -5,6 +5,8 @@ use std::ops::{Bound, RangeBounds}; use crate::{bee, error, inx}; +/// Allows to request a milestone by either its index or its id. +#[allow(missing_docs)] pub enum MilestoneRequest { MilestoneIndex(bee::MilestoneIndex), MilestoneId(bee::MilestoneId), @@ -71,6 +73,7 @@ where } } +/// Allows to request "white flag" data for a particular milestone. #[derive(Clone, Debug, PartialEq, Eq)] pub struct WhiteFlagRequest { milestone_index: bee::MilestoneIndex, diff --git a/bee-inx/src/milestone/responses.rs b/bee-inx/src/milestone/responses.rs index ddafd2ee1..ccda4f95c 100644 --- a/bee-inx/src/milestone/responses.rs +++ b/bee-inx/src/milestone/responses.rs @@ -36,6 +36,7 @@ impl From for inx::Milestone { } /// The [`Milestone`] type. +#[allow(missing_docs)] #[derive(Clone, Debug, PartialEq, Eq)] pub struct MilestoneAndProtocolParameters { pub milestone: Milestone, @@ -95,6 +96,8 @@ impl From for inx::MilestoneInfo { } } +/// The response of a corresponding "white flag" request. +#[allow(missing_docs)] #[derive(Clone, Debug, PartialEq, Eq)] pub struct WhiteFlagResponse { milestone_inclusion_merkle_root: Vec, diff --git a/bee-inx/src/node/mod.rs b/bee-inx/src/node/mod.rs index 23f1c38f9..00255b9c8 100644 --- a/bee-inx/src/node/mod.rs +++ b/bee-inx/src/node/mod.rs @@ -1,7 +1,9 @@ // Copyright 2022 IOTA Stiftung // SPDX-License-Identifier: Apache-2.0 +/// A module that provides node related INX requests. pub mod requests; +/// A module that provides node related INX responses. pub mod responses; use futures::stream::{Stream, StreamExt}; @@ -15,13 +17,13 @@ use crate::{ }; impl Inx { - /// TODO + /// Requests the status of the connected node. pub async fn read_node_status(&mut self) -> Result { NodeStatus::try_from(self.client.read_node_status(inx::NoParams {}).await?.into_inner()) .map_err(Error::InxError) } - // TODO + /// Listens to node status updates. pub async fn listen_to_node_status( &mut self, request: NodeStatusRequest, @@ -34,7 +36,7 @@ impl Inx { .map(try_from_inx_type)) } - /// TODO + /// Requests the configuration of the connected node. pub async fn read_node_configuration(&mut self) -> Result { NodeConfiguration::try_from( self.client @@ -45,7 +47,7 @@ impl Inx { .map_err(Error::InxError) } - /// TODO + /// Requests the protocol parameters of the connected node. pub async fn read_protocol_parameters(&mut self, request: MilestoneRequest) -> Result { Ok(self .client diff --git a/bee-inx/src/node/requests.rs b/bee-inx/src/node/requests.rs index 38dea8aef..6731e4bbf 100644 --- a/bee-inx/src/node/requests.rs +++ b/bee-inx/src/node/requests.rs @@ -3,7 +3,8 @@ use crate::inx; -/// TODO +/// A request for the node status. +#[allow(missing_docs)] #[derive(Clone, Debug, PartialEq, Eq)] pub struct NodeStatusRequest { pub cooldown_in_milliseconds: u32, diff --git a/bee-inx/src/node/responses.rs b/bee-inx/src/node/responses.rs index 740fca87a..86e21dcd0 100644 --- a/bee-inx/src/node/responses.rs +++ b/bee-inx/src/node/responses.rs @@ -3,7 +3,7 @@ use crate::{bee, inx, milestone::responses::Milestone, raw::Raw, return_err_if_none}; -/// The [`NodeStatus`] type. +/// Represents the [`NodeStatus`] response. #[derive(Clone, Debug, PartialEq, Eq)] pub struct NodeStatus { /// Signals if the node is healthy. @@ -64,7 +64,8 @@ impl From for inx::NodeStatus { } } -/// The [`NodeConfiguration`] type. +/// Represents the [`NodeConfiguration`] response. +#[allow(missing_docs)] #[derive(Clone, Debug, PartialEq, Eq)] pub struct NodeConfiguration { pub milestone_public_key_count: u32, @@ -108,6 +109,7 @@ impl From for inx::NodeConfiguration { } /// The [`BaseToken`] type. +#[allow(missing_docs)] #[derive(Clone, Debug, PartialEq, Eq)] pub struct BaseToken { pub name: String, @@ -144,6 +146,8 @@ impl From for inx::BaseToken { } } +/// Represents a milestone key range. +#[allow(missing_docs)] #[derive(Clone, Debug, PartialEq, Eq)] pub struct MilestoneKeyRange { pub public_key: Box<[u8]>, @@ -171,6 +175,7 @@ impl From for inx::MilestoneKeyRange { } } +/// Represents a protocol parameters response. #[allow(missing_docs)] #[derive(Clone, Debug, PartialEq, Eq)] pub struct ProtocolParameters { diff --git a/bee-inx/src/raw.rs b/bee-inx/src/raw.rs index 6f466cb26..7242697ac 100644 --- a/bee-inx/src/raw.rs +++ b/bee-inx/src/raw.rs @@ -15,17 +15,20 @@ pub struct Raw { } impl Raw { + /// Returns the inner byte data as-is. #[must_use] pub fn data(self) -> Vec { self.data } + /// Deserializes the inner byte data into `T`. pub fn inner(self, visitor: &T::UnpackVisitor) -> Result { let unpacked = T::unpack_verified(self.data, visitor) .map_err(|e| bee_block::InxError::InvalidRawBytes(format!("{:?}", e)))?; Ok(unpacked) } + /// Deserializes the raw byte data into `T` without verification. pub fn inner_unverified(self) -> Result { let unpacked = T::unpack_unverified(self.data).map_err(|e| bee_block::InxError::InvalidRawBytes(format!("{:?}", e)))?; diff --git a/bee-inx/src/utxo/mod.rs b/bee-inx/src/utxo/mod.rs index 5c1384852..c147c621b 100644 --- a/bee-inx/src/utxo/mod.rs +++ b/bee-inx/src/utxo/mod.rs @@ -1,6 +1,7 @@ // Copyright 2022 IOTA Stiftung // SPDX-License-Identifier: Apache-2.0 +/// A module that provides utxo related INX responses. pub mod responses; use futures::{Stream, StreamExt}; @@ -16,7 +17,7 @@ use crate::{ }; impl Inx { - /// TODO + /// Requests all unspent outputs. pub async fn read_unspent_outputs( &mut self, ) -> Result>, Error> { @@ -28,7 +29,7 @@ impl Inx { .map(try_from_inx_type)) } - /// TODO + /// Creates a feed of ledger updates. pub async fn listen_to_ledger_updates( &mut self, request: MilestoneRangeRequest, @@ -41,7 +42,7 @@ impl Inx { .map(try_from_inx_type)) } - /// TODO + /// Creates a feed of treasury updates. pub async fn listen_to_treasury_updates( &mut self, request: MilestoneRangeRequest, @@ -54,7 +55,7 @@ impl Inx { .map(try_from_inx_type)) } - /// TODO + /// Requests an output by its output id. pub async fn read_output(&mut self, output_id: bee::OutputId) -> Result { Ok(self .client @@ -64,7 +65,7 @@ impl Inx { .try_into()?) } - /// TODO + /// Creates a feed of migration receipts. pub async fn listen_to_migration_receipts( &mut self, ) -> Result, Error>>, Error> { diff --git a/bee-inx/src/utxo/responses.rs b/bee-inx/src/utxo/responses.rs index fba34e97e..17b244f6f 100644 --- a/bee-inx/src/utxo/responses.rs +++ b/bee-inx/src/utxo/responses.rs @@ -3,7 +3,7 @@ use crate::{bee, inx, return_err_if_none, Raw}; -/// Represents a new output in the ledger. +/// Represents unspent output response. #[allow(missing_docs)] #[derive(Clone, Debug, PartialEq, Eq)] pub struct LedgerOutput { @@ -40,7 +40,7 @@ impl From for inx::LedgerOutput { } } -/// Represents a spent output in the ledger. +/// A spent output response. #[allow(missing_docs)] #[derive(Clone, Debug, PartialEq, Eq)] pub struct LedgerSpent { @@ -74,6 +74,7 @@ impl From for inx::LedgerSpent { } } +/// An unspent output response. #[allow(missing_docs)] #[derive(Clone, Debug, PartialEq, Eq)] pub struct UnspentOutput { @@ -101,6 +102,7 @@ impl From for inx::UnspentOutput { } } +/// A ledger update response. #[allow(missing_docs)] #[derive(Clone, Debug, PartialEq, Eq)] pub enum LedgerUpdate { @@ -171,6 +173,7 @@ impl From for inx::LedgerUpdate { } } +/// Represents a ledger update batch marker. #[allow(missing_docs)] #[derive(Clone, Debug, PartialEq, Eq)] pub struct Marker { @@ -283,14 +286,6 @@ impl From for inx::TreasuryUpdate { } } -// message OutputResponse { -// uint32 ledger_index = 1; -// oneof payload { -// LedgerOutput output = 2; -// LedgerSpent spent = 3; -// } -// } - /// Represents an output response. #[allow(missing_docs)] #[derive(Clone, Debug, PartialEq, Eq)] @@ -299,6 +294,7 @@ pub struct OutputResponse { pub payload: Option, } +#[allow(missing_docs)] #[derive(Clone, Debug, PartialEq, Eq)] pub enum OutputResponsePayload { LedgerOutput(LedgerOutput),