docs(bindings): add documentation

packages/bindings/Cargo.toml

@@ -34,3 +34,7 @@ cosmwasm-std = { workspace = true }
 schemars = { workspace = true }
 serde = { workspace = true }
 thiserror = { workspace = true }
+
+[package.metadata.docs.rs]
+all-features = true
+rustdoc-args = ["--cfg", "docsrs"]

packages/bindings/src/lib.rs

@@ -1,3 +1,11 @@
+#![crate_name = "archway_bindings"]
+#![doc = include_str!("../README.md")]
+#![doc(html_logo_url = "https://avatars.githubusercontent.com/u/86496504?s=100")]
+#![cfg_attr(docsrs, feature(doc_cfg))]
+#![allow(rustdoc::bare_urls, clippy::derive_partial_eq_without_eq)]
+#![forbid(unsafe_code)]
+#![warn(trivial_casts, trivial_numeric_casts, unused_import_braces)]
+
 mod msg;
 mod pagination;
 mod query;
@@ -13,4 +21,7 @@ pub use query::ArchwayQuery;
 
 pub type Coins = Vec<cosmwasm_std::Coin>;
 
+/// A result type for [responses](cosmwasm_std::Response<ArchwayMsg>) that contain an ArchwayMsg.
+///
+/// This is a convenience type to avoid writing out the full type signature.
 pub type ArchwayResult<E> = Result<cosmwasm_std::Response<ArchwayMsg>, E>;

packages/bindings/src/msg.rs

@@ -1,19 +1,56 @@
 use cosmwasm_schema::cw_serde;
 use cosmwasm_std::{Coin, CosmosMsg, CustomMsg};
 
+/// Custom messages to interact with the Archway Network bindings.
+///
+/// Those messages work in conjunction with the `cosmwasm_std::CosmosMsg::Custom` variant.
+///
+/// # Examples
+///
+/// ```
+/// use cosmwasm_std::CosmosMsg;
+/// use archway_bindings::ArchwayMsg;
+///
+/// let msg: CosmosMsg<ArchwayMsg> = CosmosMsg::Custom(
+///     ArchwayMsg::UpdateContractMetadata {
+///         contract_address: Some(String::from("contract_address")),
+///         owner_address: Some(String::from("owner")),
+///         rewards_address: Some(String::from("rewards")),
+///     }
+/// );
 #[cw_serde]
 pub enum ArchwayMsg {
+    /// Updates a contract's metadata. Either `owner_address` or `rewards_address` must be provided.
     UpdateContractMetadata {
+        /// If set to `None`, the metadata of the sender contract will be updated.
+        /// In case the `contract_address` already has a metadata, the sender contract must be set
+        /// as the `owner_address` to be able to update it.
         contract_address: Option<String>,
+        /// If set to `None`, the contract's owner will not be updated.
         owner_address: Option<String>,
+        /// If set to `None`, the contract's rewards address will not be updated.
         rewards_address: Option<String>,
     },
+    /// Sets a premium fee for a contract. This action should be executed from a contract only if
+    /// it's set as the `owner_address` in the metadata of `contract_address`. The tx will fail if
+    /// the `contract_address` has no metadata.
     SetFlatFee {
         contract_address: Option<String>,
         flat_fee_amount: Coin,
     },
+    /// Withdraws rewards from the contract. This action should be executed from a contract only if
+    /// it's set as the `rewards_address` in a contract metadata. Only one of `records_limit` or
+    /// `record_ids` should be set.
+    ///
+    /// # See also
+    ///
+    /// * [crate::types::rewards::WithdrawRewardsResponse]
     WithdrawRewards {
+        /// Withdraw rewards up to a specified limit. If set to `None`, all rewards will be
+        /// withdrawn up to the limit of records specified by the governance parameter
+        /// `rewards.MaxWithdrawRecords`.
         records_limit: Option<u64>,
+        /// Withdraw rewards by a list of record IDs.
         record_ids: Vec<u64>,
     },
 }
@@ -27,6 +64,11 @@ impl From<ArchwayMsg> for CosmosMsg<ArchwayMsg> {
 }
 
 impl ArchwayMsg {
+    /// Creates an `ArchwayMsg` to update the current contract's metadata ownership.
+    ///
+    /// # Arguments
+    ///
+    /// * `owner_address` - The new owner address.
     pub fn update_rewards_ownership(owner_address: impl Into<String>) -> Self {
         ArchwayMsg::UpdateContractMetadata {
             contract_address: None,
@@ -35,6 +77,12 @@ impl ArchwayMsg {
         }
     }
 
+    /// Creates an `ArchwayMsg` to update the ownership of an external contract metadata.
+    ///
+    /// # Arguments
+    ///
+    /// * `contract_address` - The other contract address.
+    /// * `owner_address` - The new owner address.
     pub fn update_external_rewards_ownership(
         contract_address: impl Into<String>,
         owner_address: impl Into<String>,
@@ -46,6 +94,11 @@ impl ArchwayMsg {
         }
     }
 
+    /// Creates an `ArchwayMsg` to update the current contract's rewards address.
+    ///
+    /// # Arguments
+    ///
+    /// * `rewards_address` - The new rewards address.
     pub fn update_rewards_address(rewards_address: impl Into<String>) -> Self {
         ArchwayMsg::UpdateContractMetadata {
             contract_address: None,
@@ -54,6 +107,12 @@ impl ArchwayMsg {
         }
     }
 
+    /// Creates an `ArchwayMsg` to update the rewards address of an external contract metadata.
+    ///
+    /// # Arguments
+    ///
+    /// * `contract_address` - The other contract address.
+    /// * `rewards_address` - The new rewards address.
     pub fn update_external_rewards_address(
         contract_address: impl Into<String>,
         rewards_address: impl Into<String>,
@@ -65,20 +124,46 @@ impl ArchwayMsg {
         }
     }
 
+    /// Creates an `ArchwayMsg` to set a flat fee for a contract.
+    ///
+    /// This action should be executed from a contract only if it's set as the `owner_address` in
+    /// the metadata of `contract_address`. The tx will fail if the `contract_address` has no
+    /// metadata.
+    ///
+    /// # Arguments
+    ///
+    /// * `contract_address` - The contract address.
+    /// * `amount` - The flat fee amount.
     pub fn set_flat_fee(contract_address: impl Into<String>, amount: Coin) -> Self {
         ArchwayMsg::SetFlatFee {
             contract_address: Some(contract_address.into()),
             flat_fee_amount: amount,
         }
     }
 
+    /// Creates an `ArchwayMsg` to withdraw rewards from the contract.
+    ///
+    /// This action should be executed from a contract only if its set as the `rewards_address` in
+    /// a contract metadata.
+    ///
+    /// # Arguments
+    ///
+    /// * `limit` - Withdraw rewards up to a specified limit.
     pub fn withdraw_rewards_by_limit(limit: u64) -> Self {
         ArchwayMsg::WithdrawRewards {
             records_limit: Some(limit),
             record_ids: vec![],
         }
     }
 
+    /// Creates an `ArchwayMsg` to withdraw rewards from the contract by a list of record IDs.
+    ///
+    /// This action should be executed from a contract only if its set as the `rewards_address` in
+    /// a contract metadata.
+    ///
+    /// # Arguments
+    ///
+    /// * `record_ids` - List of record IDs to withdraw rewards from the rewards pool.
     pub fn withdraw_rewards_by_ids(record_ids: Vec<u64>) -> Self {
         ArchwayMsg::WithdrawRewards {
             records_limit: None,

packages/bindings/src/pagination.rs

@@ -1,5 +1,7 @@
 use cosmwasm_schema::cw_serde;
 
+/// WASM binding version for the Cosmos SDK [`query.PageRequest`](https://github.com/cosmos/cosmos-sdk/blob/v0.45.16/proto/cosmos/base/query/v1beta1/pagination.proto),
+/// embedded in request messages for efficient pagination.
 #[cw_serde]
 #[derive(Default)]
 pub struct PageRequest {
@@ -15,34 +17,48 @@ impl PageRequest {
         Self::default()
     }
 
+    /// The `key` is a value returned in `PageResponse.next_key` to begin querying the next page
+    /// most efficiently. Only one of offset or key should be set.
     pub fn key(mut self, key: impl Into<String>) -> Self {
         self.key = Some(key.into());
         self
     }
 
+    /// A numeric offset that can be used when key is unavailable. It is less efficient than using
+    /// key. Only one of offset or key should be set.
     pub fn offset(mut self, offset: u64) -> Self {
         self.offset = Some(offset);
         self
     }
 
+    /// Total number of results to be returned in the result page. If left empty, it will default
+    /// to a value to be set by each app.
     pub fn limit(mut self, limit: u64) -> Self {
         self.limit = Some(limit);
         self
     }
 
+    /// When set to `true`, indicates that the result set should include a count of the total number
+    /// of items available for pagination. `count_total` is only respected when `offset` is used.
+    /// It is ignored when `key` is set.
     pub fn count_total(mut self) -> Self {
         self.count_total = Some(true);
         self
     }
 
+    /// If set to `true`, the results will be returned in the descending order.
     pub fn reverse(mut self) -> Self {
         self.reverse = Some(true);
         self
     }
 }
 
+/// Embedded in response messages where the corresponding request message has used a [`PageRequest`].
 #[cw_serde]
 pub struct PageResponse {
+    /// Key to be passed to `PageRequest.key` to query the next page most efficiently.
     pub next_key: Option<String>,
+    /// Total number of results available if `PageRequest.count_total` was set; its value is
+    /// `None` otherwise
     pub total: Option<u64>,
 }

packages/bindings/src/query.rs

@@ -4,44 +4,57 @@ use cosmwasm_std::CustomQuery;
 use crate::pagination::PageRequest;
 use crate::types::{gov, rewards};
 
+/// Queries for Archway's bindings.
 #[cw_serde]
 #[derive(QueryResponses)]
 pub enum ArchwayQuery {
+    /// Returns a [rewards::ContractMetadataResponse] for the given contract address.
     #[returns(rewards::ContractMetadataResponse)]
     ContractMetadata { contract_address: String },
+    /// Returns a [rewards::FlatFeeResponse for the given contract address.
     #[returns(rewards::FlatFeeResponse)]
     FlatFee { contract_address: String },
+    /// Returns a [rewards::RewardsRecordsResponse] containing a list of [rewards::RewardsRecord]
+    /// objects that are credited for the account and are ready to be withdrawn. The request is
+    /// paginated. If the limit field is not set, the governance param `rewards.MaxWithdrawRecords`
+    /// is used.
     #[returns(rewards::RewardsRecordsResponse)]
     RewardsRecords {
         rewards_address: String,
         pagination: Option<PageRequest>,
     },
+    /// Returns a [gov::VoteResponse] for the given proposal ID and voter.
     #[returns(gov::VoteResponse)]
     GovVote { proposal_id: u64, voter: String },
 }
 
 impl CustomQuery for ArchwayQuery {}
 
 impl ArchwayQuery {
+    /// Builds a query to get the contract metadata for the given contract address.
     pub fn contract_metadata(contract_address: impl Into<String>) -> Self {
         ArchwayQuery::ContractMetadata {
             contract_address: contract_address.into(),
         }
     }
 
+    /// Builds a query to get the flat fee for the given contract address.
     pub fn flat_fee(contract_address: impl Into<String>) -> Self {
         ArchwayQuery::FlatFee {
             contract_address: contract_address.into(),
         }
     }
 
+    /// Builds a query to list the rewards records for the given rewards address.
     pub fn rewards_records(rewards_address: impl Into<String>) -> Self {
         ArchwayQuery::RewardsRecords {
             rewards_address: rewards_address.into(),
             pagination: None,
         }
     }
 
+    /// Builds a query to get a list of rewards records for the given rewards address with
+    /// pagination.
     pub fn rewards_records_with_pagination(
         rewards_address: impl Into<String>,
         pagination: PageRequest,
@@ -52,6 +65,7 @@ impl ArchwayQuery {
         }
     }
 
+    /// Builds a query to get the vote for the given proposal ID and voter.
     pub fn gov_vote(proposal_id: u64, voter: impl Into<String>) -> Self {
         ArchwayQuery::GovVote {
             proposal_id,

packages/bindings/src/types/rewards.rs

@@ -3,34 +3,55 @@ use cosmwasm_std::Coin;
 
 use crate::{Coins, PageResponse};
 
-#[cw_serde]
-pub struct WithdrawRewardsResponse {
-    pub records_num: u64,
-    pub total_rewards: Coins,
-}
-
+/// Response to a [crate::ArchwayQuery::ContractMetadata] query.
 #[cw_serde]
 pub struct ContractMetadataResponse {
+    /// Address of the contract owner (the one who can modify rewards parameters).
     pub owner_address: String,
+    /// Address of the rewards (the one who can withdraw rewards).
     pub rewards_address: String,
 }
 
+/// Response to a [crate::ArchwayQuery::FlatFee] query.
 #[cw_serde]
 pub struct FlatFeeResponse {
     pub flat_fee_amount: Coin,
 }
 
+/// Response to a [crate::ArchwayQuery::RewardsRecords] query.
 #[cw_serde]
 pub struct RewardsRecordsResponse {
     pub records: Vec<RewardsRecord>,
     pub pagination: Option<PageResponse>,
 }
 
+/// Defines a record that is used to distribute rewards later (lazy distribution). This record is
+/// created by the `x/rewards` EndBlocker and pruned after the rewards are distributed. An actual
+/// rewards `x/bank` transfer can be triggered by a contract via WASM bindings. For a contract to
+/// trigger rewards transfer, the sender contract address must be set as the `rewards_address` in
+/// the corresponding ContractMetadata.
 #[cw_serde]
 pub struct RewardsRecord {
+    /// The unique ID of the record.
     pub id: u64,
+    /// Address to distribute rewards to (bech32 encoded).
     pub rewards_address: String,
+    /// Rewards amount to distribute.
     pub rewards: Coins,
+    /// Height at which the record was created.
     pub calculated_height: i64,
+    /// Time at which the record was created, in RFC3339Nano format.
     pub calculated_time: String,
 }
+
+/// Returned by a [crate::ArchwayMsg::WithdrawRewards] message. It can be accessed by listening to
+/// a reply from the message.
+///
+/// See the [sample contract](https://github.com/archway-network/arch3.rs/blob/main/contracts/increment/src/contract.rs) for an example.
+#[cw_serde]
+pub struct WithdrawRewardsResponse {
+    /// The number of records that were withdrawn.
+    pub records_num: u64,
+    /// The total amount of rewards that were withdrawn.
+    pub total_rewards: Coins,
+}