From 69f3a13a2620360131a1e79497d7abad1e306cef Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Augusto=20Elesb=C3=A3o?= Date: Fri, 13 Oct 2023 11:23:00 +0200 Subject: [PATCH] docs(bindings): add documentation --- packages/bindings/Cargo.toml | 4 ++ packages/bindings/src/lib.rs | 11 ++++ packages/bindings/src/msg.rs | 85 ++++++++++++++++++++++++++ packages/bindings/src/pagination.rs | 16 +++++ packages/bindings/src/query.rs | 14 +++++ packages/bindings/src/types/rewards.rs | 33 ++++++++-- 6 files changed, 157 insertions(+), 6 deletions(-) diff --git a/packages/bindings/Cargo.toml b/packages/bindings/Cargo.toml index 198071e..745b2ae 100644 --- a/packages/bindings/Cargo.toml +++ b/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"] diff --git a/packages/bindings/src/lib.rs b/packages/bindings/src/lib.rs index 593a841..57d74b6 100644 --- a/packages/bindings/src/lib.rs +++ b/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; +/// A result type for [responses](cosmwasm_std::Response) that contain an ArchwayMsg. +/// +/// This is a convenience type to avoid writing out the full type signature. pub type ArchwayResult = Result, E>; diff --git a/packages/bindings/src/msg.rs b/packages/bindings/src/msg.rs index ad631ad..b1aa6cc 100644 --- a/packages/bindings/src/msg.rs +++ b/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 = 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, + /// If set to `None`, the contract's owner will not be updated. owner_address: Option, + /// If set to `None`, the contract's rewards address will not be updated. rewards_address: Option, }, + /// 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, 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, + /// Withdraw rewards by a list of record IDs. record_ids: Vec, }, } @@ -27,6 +64,11 @@ impl From for CosmosMsg { } 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) -> 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, owner_address: impl Into, @@ -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) -> 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, rewards_address: impl Into, @@ -65,6 +124,16 @@ 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, amount: Coin) -> Self { ArchwayMsg::SetFlatFee { contract_address: Some(contract_address.into()), @@ -72,6 +141,14 @@ impl ArchwayMsg { } } + /// 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), @@ -79,6 +156,14 @@ impl ArchwayMsg { } } + /// 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) -> Self { ArchwayMsg::WithdrawRewards { records_limit: None, diff --git a/packages/bindings/src/pagination.rs b/packages/bindings/src/pagination.rs index abf1da7..678fc6a 100644 --- a/packages/bindings/src/pagination.rs +++ b/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) -> 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, + /// Total number of results available if `PageRequest.count_total` was set; its value is + /// `None` otherwise pub total: Option, } diff --git a/packages/bindings/src/query.rs b/packages/bindings/src/query.rs index e2e7b01..9398a35 100644 --- a/packages/bindings/src/query.rs +++ b/packages/bindings/src/query.rs @@ -4,18 +4,26 @@ 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, }, + /// Returns a [gov::VoteResponse] for the given proposal ID and voter. #[returns(gov::VoteResponse)] GovVote { proposal_id: u64, voter: String }, } @@ -23,18 +31,21 @@ pub enum ArchwayQuery { 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) -> 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) -> 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) -> Self { ArchwayQuery::RewardsRecords { rewards_address: rewards_address.into(), @@ -42,6 +53,8 @@ impl ArchwayQuery { } } + /// 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, 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) -> Self { ArchwayQuery::GovVote { proposal_id, diff --git a/packages/bindings/src/types/rewards.rs b/packages/bindings/src/types/rewards.rs index 2acfa6b..840c523 100644 --- a/packages/bindings/src/types/rewards.rs +++ b/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, pub pagination: Option, } +/// 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, +}