Properly define and document our public interface

.changelog/unreleased/breaking-changes/235-cleanup-modules-exposed.md

@@ -0,0 +1,2 @@
+- Reduce and consolidate the amount of public modules exposed
+  ([#235](https://github.com/cosmos/ibc-rs/issues/235))

.changelog/unreleased/breaking-changes/597-type-urls-private.md

@@ -0,0 +1 @@
+- Make `TYPE_URL`s private ([#597](https://github.com/cosmos/ibc-rs/issues/597))

.changelog/unreleased/improvements/376-docstrings.md

@@ -0,0 +1,2 @@
+- Document every method of `ValidationContext` and `ExecutionContext`
+  ([#376](https://github.com/cosmos/ibc-rs/issues/376))

crates/ibc/src/applications/mod.rs

@@ -1,4 +1,4 @@
-//! Various packet encoding semantics which underpin the various types of transactions.
+//! Implementation of IBC applications
 
 #[cfg(feature = "serde")]
 pub mod transfer;

crates/ibc/src/applications/transfer/acknowledgement.rs

@@ -1,8 +1,9 @@
+//! Defines types used in token transfer acknowledgements
+
 use core::fmt::{Display, Error as FmtError, Formatter};
 
 use super::error::TokenTransferError;
-use crate::core::ics04_channel::msgs::acknowledgement::Acknowledgement;
-use crate::prelude::*;
+use crate::{core::ics04_channel::packet::Acknowledgement, prelude::*};
 
 /// A string constant included in error acknowledgements.
 /// NOTE: Changing this const is state machine breaking as acknowledgements are written into state

crates/ibc/src/applications/transfer/amount.rs

@@ -1,3 +1,5 @@
+//! Contains the `Amount` type, which represents amounts of tokens transferred.
+
 use core::str::FromStr;
 use derive_more::{Display, From, Into};
 

crates/ibc/src/applications/transfer/coin.rs

@@ -1,3 +1,5 @@
+//! Defines coin types; the objects that are being transferred.
+
 use core::fmt::{Display, Error as FmtError, Formatter};
 use core::str::{from_utf8, FromStr};
 use ibc_proto::cosmos::base::v1beta1::Coin as ProtoCoin;

crates/ibc/src/applications/transfer/context.rs

@@ -1,3 +1,6 @@
+//! Defines the main context traits and IBC module callbacks
+
+use crate::core::router::ModuleExtras;
 use crate::core::ContextError;
 use crate::prelude::*;
 
@@ -16,13 +19,12 @@ use crate::core::ics04_channel::channel::{Counterparty, Order};
 use crate::core::ics04_channel::context::{
     SendPacketExecutionContext, SendPacketValidationContext,
 };
-use crate::core::ics04_channel::handler::ModuleExtras;
-use crate::core::ics04_channel::msgs::acknowledgement::Acknowledgement;
-use crate::core::ics04_channel::packet::Packet;
+use crate::core::ics04_channel::packet::{Acknowledgement, Packet};
 use crate::core::ics04_channel::Version;
 use crate::core::ics24_host::identifier::{ChannelId, ConnectionId, PortId};
 use crate::signer::Signer;
 
+/// Methods required in token transfer validation, to be implemented by the host
 pub trait TokenTransferValidationContext: SendPacketValidationContext {
     type AccountId: TryFrom<Signer>;
 
@@ -71,6 +73,7 @@ pub trait TokenTransferValidationContext: SendPacketValidationContext {
     }
 }
 
+/// Methods required in token transfer execution, to be implemented by the host
 pub trait TokenTransferExecutionContext:
     TokenTransferValidationContext + SendPacketExecutionContext
 {

crates/ibc/src/applications/transfer/denom.rs

@@ -1,3 +1,5 @@
+//! Defines types to represent "denominations" [as defined in ICS-20](https://github.com/cosmos/ibc/blob/main/spec/app/ics-020-fungible-token-transfer/README.md#data-structures)
+
 use core::fmt::{Display, Error as FmtError, Formatter};
 use core::str::FromStr;
 
@@ -11,7 +13,10 @@ use crate::prelude::*;
 #[cfg(feature = "serde")]
 use crate::serializers::serde_string;
 
-/// Base denomination type
+/// The "base" of a denomination.
+///
+/// For example, given the token `my_port-1/my_channel-1/my_port-2/my_channel-2/base_denom`,
+/// `base_denom` is the "base" of the denomination
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 #[cfg_attr(feature = "serde", serde(transparent))]
 #[cfg_attr(
@@ -43,6 +48,11 @@ impl FromStr for BaseDenom {
     }
 }
 
+/// One hop in a token's trace, which consists of the port and channel IDs of the sender
+///
+/// For example, given the token `my_port-1/my_channel-1/my_port-2/my_channel-2/base_denom`,
+/// `my_port-1/my_channel-1` is a trace prefix, and `my_port-2/my_channel-2` is another one.
+/// See [TracePath] which stitches trace prefixes together.
 #[cfg_attr(
     feature = "parity-scale-codec",
     derive(

crates/ibc/src/applications/transfer/error.rs

@@ -1,12 +1,13 @@
+//! Defines the token transfer error type
+
 use core::convert::Infallible;
 use core::str::Utf8Error;
 use displaydoc::Display;
 use ibc_proto::protobuf::Error as TendermintProtoError;
 use uint::FromDecStrErr;
 
 use crate::core::ics04_channel::channel::Order;
-use crate::core::ics24_host::error::ValidationError;
-use crate::core::ics24_host::identifier::{ChannelId, PortId};
+use crate::core::ics24_host::identifier::{ChannelId, IdentifierError, PortId};
 use crate::core::ContextError;
 use crate::prelude::*;
 
@@ -15,7 +16,7 @@ pub enum TokenTransferError {
     /// context error: `{0}`
     ContextError(ContextError),
     /// invalid identifier: `{0}`
-    InvalidIdentifier(ValidationError),
+    InvalidIdentifier(IdentifierError),
     /// destination channel not found in the counterparty of port_id `{port_id}` and channel_id `{channel_id}`
     DestinationChannelNotFound {
         port_id: PortId,
@@ -26,12 +27,12 @@ pub enum TokenTransferError {
     /// invalid prot id n trace at position: `{pos}`, validation error: `{validation_error}`
     InvalidTracePortId {
         pos: usize,
-        validation_error: ValidationError,
+        validation_error: IdentifierError,
     },
     /// invalid channel id in trace at position: `{pos}`, validation error: `{validation_error}`
     InvalidTraceChannelId {
         pos: usize,
-        validation_error: ValidationError,
+        validation_error: IdentifierError,
     },
     /// trace length must be even but got: `{len}`
     InvalidTraceLength { len: usize },
@@ -105,8 +106,8 @@ impl From<ContextError> for TokenTransferError {
     }
 }
 
-impl From<ValidationError> for TokenTransferError {
-    fn from(err: ValidationError) -> TokenTransferError {
+impl From<IdentifierError> for TokenTransferError {
+    fn from(err: IdentifierError) -> TokenTransferError {
         Self::InvalidIdentifier(err)
     }
 }

crates/ibc/src/applications/transfer/events.rs

@@ -1,14 +1,19 @@
+//! Defines all token transfer event types
+
 use crate::applications::transfer::acknowledgement::TokenTransferAcknowledgement;
-use crate::applications::transfer::{Amount, Memo, PrefixedDenom, MODULE_ID_STR};
-use crate::events::ModuleEvent;
+use crate::applications::transfer::{Amount, PrefixedDenom, MODULE_ID_STR};
+use crate::core::events::ModuleEvent;
 use crate::prelude::*;
 use crate::signer::Signer;
 
+use super::Memo;
+
 const EVENT_TYPE_PACKET: &str = "fungible_token_packet";
 const EVENT_TYPE_TIMEOUT: &str = "timeout";
 const EVENT_TYPE_DENOM_TRACE: &str = "denomination_trace";
 const EVENT_TYPE_TRANSFER: &str = "ibc_transfer";
 
+/// Contains all events variants that can be emitted from the token transfer application
 pub enum Event {
     Recv(RecvEvent),
     Ack(AckEvent),
@@ -18,6 +23,8 @@ pub enum Event {
     Transfer(TransferEvent),
 }
 
+/// Event emitted in the [`onRecvPacket`][super::context::on_recv_packet_execute]
+/// module callback to indicate the that the `RecvPacket` message was processed
 pub struct RecvEvent {
     pub sender: Signer,
     pub receiver: Signer,
@@ -52,6 +59,8 @@ impl From<RecvEvent> for ModuleEvent {
     }
 }
 
+/// Event emitted in the [`onAcknowledgePacket`][super::context::on_acknowledgement_packet_execute]
+/// module callback
 pub struct AckEvent {
     pub sender: Signer,
     pub receiver: Signer,
@@ -86,6 +95,8 @@ impl From<AckEvent> for ModuleEvent {
     }
 }
 
+/// Event emitted in the [`onAcknowledgePacket`][super::context::on_acknowledgement_packet_execute]
+/// module callback to indicate whether the acknowledgement is a success or a failure
 pub struct AckStatusEvent {
     pub acknowledgement: TokenTransferAcknowledgement,
 }
@@ -105,6 +116,8 @@ impl From<AckStatusEvent> for ModuleEvent {
     }
 }
 
+/// Event emitted in the [`onTimeoutPacket`][super::context::on_timeout_packet_execute]
+/// module callback
 pub struct TimeoutEvent {
     pub refund_receiver: Signer,
     pub refund_denom: PrefixedDenom,
@@ -133,6 +146,8 @@ impl From<TimeoutEvent> for ModuleEvent {
     }
 }
 
+/// Event emitted in the [`onRecvPacket`][super::context::on_recv_packet_execute]
+/// module callback when new tokens are minted
 pub struct DenomTraceEvent {
     pub trace_hash: Option<String>,
     pub denom: PrefixedDenom,
@@ -152,6 +167,8 @@ impl From<DenomTraceEvent> for ModuleEvent {
     }
 }
 
+/// Event emitted in [`sendTransfer`][super::send_transfer] after a successful
+/// transfer
 pub struct TransferEvent {
     pub sender: Signer,
     pub receiver: Signer,

crates/ibc/src/applications/transfer/memo.rs

@@ -1,9 +1,13 @@
+//! Defines the memo type, which represents the string that users can include
+//! with a token transfer
+
 use core::convert::Infallible;
 use core::fmt::{self, Display};
 use core::str::FromStr;
 
 use crate::prelude::*;
 
+/// Represents the token transfer memo
 #[cfg_attr(
     feature = "parity-scale-codec",
     derive(

crates/ibc/src/applications/transfer/mod.rs

@@ -1,6 +1,5 @@
-//! ICS 20: Token Transfer implementation allows for multi-chain denomination handling, which
-//! constitutes a "fungible token transfer bridge module" between the IBC routing module and an
-//! asset tracking module.
+//! Implementation of the [fungible token transfer module](https://github.com/cosmos/ibc/blob/main/spec/app/ics-020-fungible-token-transfer/README.md) (ICS-20)
+
 pub mod acknowledgement;
 pub mod amount;
 pub mod coin;
@@ -11,7 +10,6 @@ pub mod events;
 pub mod memo;
 pub mod msgs;
 pub mod packet;
-pub mod relay;
 
 pub use amount::*;
 pub use coin::*;
@@ -27,3 +25,7 @@ pub const PORT_ID_STR: &str = "transfer";
 
 /// ICS20 application current version.
 pub const VERSION: &str = "ics20-1";
+
+mod relay;
+
+pub use relay::send_transfer::{send_transfer, send_transfer_execute, send_transfer_validate};

crates/ibc/src/applications/transfer/msgs.rs

@@ -1 +1,3 @@
+//! Defines the token transfer message type
+
 pub mod transfer;

crates/ibc/src/applications/transfer/msgs/transfer.rs

@@ -1,4 +1,4 @@
-//! This is the definition of a transfer messages that an application submits to a chain.
+//! Defines the token transfer message type
 
 use crate::prelude::*;
 
@@ -11,11 +11,10 @@ use crate::applications::transfer::packet::PacketData;
 use crate::core::ics04_channel::error::PacketError;
 use crate::core::ics04_channel::timeout::TimeoutHeight;
 use crate::core::ics24_host::identifier::{ChannelId, PortId};
-use crate::core::ContextError;
-use crate::timestamp::Timestamp;
-use crate::tx_msg::Msg;
+use crate::core::timestamp::Timestamp;
+use crate::core::{ContextError, Msg};
 
-pub const TYPE_URL: &str = "/ibc.applications.transfer.v1.MsgTransfer";
+pub(crate) const TYPE_URL: &str = "/ibc.applications.transfer.v1.MsgTransfer";
 
 /// Message used to build an ICS20 token transfer packet.
 ///
@@ -119,7 +118,8 @@ impl TryFrom<Any> for MsgTransfer {
 
 #[cfg(test)]
 pub mod test_util {
-    use alloc::borrow::ToOwned;
+    use super::*;
+
     use core::ops::Add;
     use core::time::Duration;
     use primitive_types::U256;
@@ -134,7 +134,6 @@ pub mod test_util {
         applications::transfer::BaseCoin,
         core::ics24_host::identifier::{ChannelId, PortId},
         test_utils::get_dummy_bech32_account,
-        timestamp::Timestamp,
     };
 
     // Returns a dummy ICS20 `MsgTransfer`. If no `timeout_timestamp` is

crates/ibc/src/applications/transfer/packet.rs

@@ -1,3 +1,5 @@
+//! Contains the `PacketData` type that defines the structure of token transfers' packet bytes
+
 use alloc::string::ToString;
 use core::convert::TryFrom;
 use core::str::FromStr;
@@ -8,6 +10,7 @@ use super::error::TokenTransferError;
 use super::{Amount, Memo, PrefixedCoin, PrefixedDenom};
 use crate::signer::Signer;
 
+/// Defines the structure of token transfers' packet bytes
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 #[cfg_attr(
     feature = "serde",

crates/ibc/src/applications/transfer/relay.rs

@@ -1,4 +1,5 @@
-//! This module implements the processing logic for ICS20 (token transfer) message.
+//! Implements the processing logic for ICS20 (token transfer) message.
+
 use crate::applications::transfer::error::TokenTransferError;
 use crate::applications::transfer::is_sender_chain_source;
 use crate::applications::transfer::packet::PacketData;

crates/ibc/src/applications/transfer/relay/on_recv_packet.rs

@@ -3,8 +3,8 @@ use crate::applications::transfer::error::TokenTransferError;
 use crate::applications::transfer::events::DenomTraceEvent;
 use crate::applications::transfer::packet::PacketData;
 use crate::applications::transfer::{is_receiver_chain_source, TracePrefix};
-use crate::core::ics04_channel::handler::ModuleExtras;
 use crate::core::ics04_channel::packet::Packet;
+use crate::core::router::ModuleExtras;
 use crate::prelude::*;
 
 /// This function handles the transfer receiving logic.

crates/ibc/src/applications/transfer/relay/send_transfer.rs

@@ -5,15 +5,13 @@ use crate::applications::transfer::error::TokenTransferError;
 use crate::applications::transfer::events::TransferEvent;
 use crate::applications::transfer::msgs::transfer::MsgTransfer;
 use crate::applications::transfer::{is_sender_chain_source, MODULE_ID_STR};
+use crate::core::events::{MessageEvent, ModuleEvent};
 use crate::core::ics04_channel::handler::send_packet::{send_packet_execute, send_packet_validate};
 use crate::core::ics04_channel::packet::Packet;
 use crate::core::ics24_host::path::{ChannelEndPath, SeqSendPath};
-use crate::events::{MessageEvent, ModuleEvent};
 use crate::prelude::*;
 
-/// This function handles the transfer sending logic.
-/// If this method returns an error, the runtime is expected to rollback all state modifications to
-/// the `Ctx` caused by all messages from the transaction that this `msg` is a part of.
+/// Initiate a token transfer. Equivalent to calling [`send_transfer_validate`], followed by [`send_transfer_execute`].
 pub fn send_transfer<Ctx>(ctx_a: &mut Ctx, msg: MsgTransfer) -> Result<(), TokenTransferError>
 where
     Ctx: TokenTransferExecutionContext,
@@ -22,6 +20,7 @@ where
     send_transfer_execute(ctx_a, msg)
 }
 
+/// Validates the token tranfer. If this succeeds, then it is legal to initiate the transfer with [`send_transfer_execute`].
 pub fn send_transfer_validate<Ctx>(ctx_a: &Ctx, msg: MsgTransfer) -> Result<(), TokenTransferError>
 where
     Ctx: TokenTransferValidationContext,
@@ -85,6 +84,7 @@ where
     Ok(())
 }
 
+/// Executes the token transfer. A prior call to [`send_transfer_validate`] MUST have succeeded.
 pub fn send_transfer_execute<Ctx>(
     ctx_a: &mut Ctx,
     msg: MsgTransfer,