Fixed documentation

Baseflow · Sep 10, 2024 · 0aefc0e · 0aefc0e
1 parent ff7db09
commit 0aefc0e
Show file tree

Hide file tree

Showing 21 changed files with 211 additions and 175 deletions.
diff --git a/README.md b/README.md
@@ -1,33 +1,113 @@
-# Rust Stellar SDK - Empowering Stellar Developers with Rust's Performance and Security
+# Stellar-rs - Empowering Stellar Developers with Rust's Performance and Security
 
-## Badges
-
-![GitHub Workflow Status (with event)](https://img.shields.io/github/actions/workflow/status/Baseflow/stellar-rust-sdk/.github%2Fworkflows%2Fcargo-build-and-test.yaml)
+![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/Baseflow/stellar-rust-sdk/.github%2Fworkflows%2Fcargo-build-and-test.yaml)
 [![Crates.io](https://img.shields.io/crates/v/stellar-sdk.svg)](https://crates.io/crates/stellar-rs)
 [![Documentation](https://img.shields.io/badge/documentation-1)](https://docs.rs/stellar-rs/latest/stellar_rs/index.html)
-[![GitHub issues](https://img.shields.io/github/issues/Baseflow/stellar-rust-sdk)]()
-[![GitHub stars](https://img.shields.io/github/stars/Baseflow/stellar-rust-sdk)]()
-[![GitHub license](https://img.shields.io/github/license/Baseflow/stellar-rust-sdk)]()
+[![GitHub Issues](https://img.shields.io/github/issues/Baseflow/stellar-rust-sdk)]()
+[![GitHub Stars](https://img.shields.io/github/stars/Baseflow/stellar-rust-sdk)]()
+[![GitHub License](https://img.shields.io/github/license/Baseflow/stellar-rust-sdk)]()
+
+API documentation is available [here](https://docs.rs/stellar-rs/1.0.0).
+
+The Rust Stellar SDK enables efficient and safe communication with [Stellar's
+Horizon API](https://developers.stellar.org/docs/data/horizon). Our goal is to
+provide an optimal developer experience by utilizing Rust's performance and
+safety features. By employing the [Type State Builder
+Pattern](https://www.youtube.com/watch?v=pwmIQzLuYl0), we prevent incomplete or
+invalid requests from being made, reducing the possibility of runtime exceptions
+and improving API request reliability.
+
+## Installation
+
+To add `stellar-rs` to your project, run the following Cargo command in your
+project directory:
+
+```bash
+cargo add stellar-rs
+```
+
+Alternatively, add the following line to your `Cargo.toml`:
+
+```toml
+stellar-rs = "1.0.0"
+```
+
+## Getting Started
+
+To begin communicating with the Horizon API, initialize a new Horizon client.
+You can specify whether to use the testnet or the production environment.
+
+```rust
+use stellar_rs::horizon_client::HorizonClient;
+
+async fn example() -> Result<(), Box<dyn std::error::Error>> {
+    let horizon_client = HorizonClient::new("https://horizon-testnet.stellar.org")?;
+    Ok(())
+}
+```
+
+After initializing the Horizon client, specify the request you want to execute.
+The request builders ensure that you construct valid requests, preventing
+invalid parameter combinations.
+
+```rust
+use stellar_rs::assets::prelude::{AllAssetsRequest, AllAssetsResponse};
+
+static ACCOUNT_ID: &str = "GDIGRW2H37U3O5WPMQFWGN35DDVZAYYTIMGLYVQI4XTATZBW4FXEATRE";
 
+// Construct the request
+let accounts_request = AccountsRequest::new()
+    .set_signer_filter(ACCOUNT_ID)
+    .unwrap()
+    .set_limit(10)
+    .unwrap();
+```
 
+Once the `signer_filter` is set, it cannot be changed again. The state
+transitions from one where no filter is applied to one where the `signer_filter`
+is set. Similarly, methods like `set_asset_filter`, `set_liquidity_pool_filter`,
+and `set_sponsor_filter` become unavailable because the Horizon API allows only
+one of these filters per request. This is enforced using the type state builder
+pattern.
 
+Once the request is constructed, you can execute it using the previously
+initialized Horizon client:
 
-## Description:
+```rust
+use stellar_rs::assets::prelude::{AllAssetsRequest, AllAssetsResponse};
 
-Welcome to the Rust Stellar SDK repository, where we are pioneering a new era of development on the Stellar cryptocurrency network. With the aim of unlocking the full potential of Stellar and embracing the exceptional features of Rust, we present an innovative and robust Rust SDK for the Stellar ecosystem.
+let accounts_response = horizon_client.get_account_list(&accounts_request).await?;
+```
 
-## Why Rust?
+## Supported Endpoints
 
-While Stellar has already established itself as a versatile platform with SDKs in various programming languages, the absence of a Rust SDK has limited developers from leveraging Rust's unique strengths. Rust's reputation for performance, reliability, and security makes it an ideal language for building efficient, scalable, and secure applications. Recognizing the growing popularity of Rust, we set out on a mission to bridge this gap and empower developers to harness the power of Rust in the Stellar network.
+As of version 1.0, `stellar-rs` supports all endpoints and models for the Horizon API:
 
-## Setting the Stage for Future Growth
+* [Accounts](https://developers.stellar.org/docs/data/horizon/api-reference/resources/accounts)
+* [Assets](https://developers.stellar.org/docs/data/horizon/api-reference/resources/assets)
+* [Claimable Balances](https://developers.stellar.org/docs/data/horizon/api-reference/resources/claimablebalances)
+* [Effects](https://developers.stellar.org/docs/data/horizon/api-reference/resources/effects)
+* [Fee Stats](https://developers.stellar.org/docs/data/horizon/api-reference/aggregations/fee-stats)
+* [Ledgers](https://developers.stellar.org/docs/data/horizon/api-reference/resources/ledgers)
+* [Liquidity Pools](https://developers.stellar.org/docs/data/horizon/api-reference/resources/liquiditypools)
+* [Operations](https://developers.stellar.org/docs/data/horizon/api-reference/resources/operations)
+* [Offers](https://developers.stellar.org/docs/data/horizon/api-reference/resources/offers)
+* [Order Books](https://developers.stellar.org/docs/data/horizon/api-reference/aggregations/order-books)
+* [Paths](https://developers.stellar.org/docs/data/horizon/api-reference/aggregations/paths)
+* [Payments](https://developers.stellar.org/docs/data/horizon/api-reference/resources/payments)
+* [Trades](https://developers.stellar.org/docs/data/horizon/api-reference/resources/trades)
+* [Trade Aggregations](https://developers.stellar.org/docs/data/horizon/api-reference/aggregations/trade-aggregations)
+* [Transactions](https://developers.stellar.org/docs/data/horizon/api-reference/resources/transactions)
 
-Our dedication to driving Stellar's evolution led us to establish a Rust tooling ecosystem, creating a solid foundation for seamless integration with upcoming features and projects like the Soroban platform. As Rust development continues to gain momentum, it is imperative for Stellar to embrace this trend and provide developers with the necessary tools to stay ahead in the rapidly evolving cryptocurrency landscape.
+## Contributing
 
-## Joining Forces - A Collaborative Environment
+Contributions are welcome! If you find a bug or have a feature request, please
+[open an issue](https://github.com/Baseflow/stellar-rust-sdk/issues). If you'd
+like to contribute code, feel free to open a pull request.
 
-By integrating Rust into the Stellar network, we foster an inclusive and collaborative environment where both the Rust and Stellar communities can work together, exchange insights, and push the ecosystem's growth. Our mission is to create an ecosystem that encourages innovation, enables developers to build exceptional applications, and enhances the overall capabilities of the Stellar network.
+## License
 
-## Enterprise-Grade Quality and Stability
+This project is licensed under the MIT License. See [LICENSE-MIT](./LICENSE) or
+visit [https://opensource.org/licenses/MIT](https://opensource.org/licenses/MIT)
+for more information.
 
-At Baseflow, quality is at the heart of everything we do. With a proven track record of delivering top-notch software solutions to esteemed companies like Google and Deloitte, our focus on quality and stability is unwavering. The Rust SDK for Stellar will undergo rigorous testing, adhere to best practices, and undergo thorough code reviews, ensuring the highest standards of stability, security, and performance. We understand the criticality of the financial sector and are committed to inspiring confidence in developers and users alike.
diff --git a/stellar_rust_sdk/src/accounts/accounts_request.rs b/stellar_rust_sdk/src/accounts/accounts_request.rs
@@ -18,7 +18,7 @@ use crate::{models::*, BuildQueryParametersExt};
 /// # use stellar_rs::horizon_client::HorizonClient;
 /// #
 /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
-/// # let base_url = "https://horizon-testnet.stellar.org".to_string();
+/// # let base_url = "https://horizon-testnet.stellar.org";
 /// # let horizon_client = HorizonClient::new(base_url)
 /// #    .expect("Failed to create Horizon Client");
 /// let request = AccountsRequest::new()
@@ -196,7 +196,7 @@ macro_rules! valid_generic_account_request_impl {
 /// # use stellar_rs::accounts::prelude::AccountsRequest;
 /// # use stellar_rs::horizon_client::HorizonClient;
 /// # use stellar_rs::models::Request;
-/// # let horizon_client = HorizonClient::new("https://horizon-testnet.stellar.org".to_string()).unwrap();
+/// # let horizon_client = HorizonClient::new("https://horizon-testnet.stellar.org").unwrap();
 /// let request = AccountsRequest::new()
 ///     .set_sponsor_filter("GDQJUTQYK2MQX2VGDR2FYWLIYAQIEGXTQVTFEMGH2BEWFG4BRUY4CKI7".to_string())
 ///     .unwrap();

diff --git a/stellar_rust_sdk/src/accounts/mod.rs b/stellar_rust_sdk/src/accounts/mod.rs
@@ -102,8 +102,7 @@ pub mod test {
     #[tokio::test]
     async fn test_get_account_list() {
         // Initialize horizon client
-        let horizon_client =
-            HorizonClient::new("https://horizon-testnet.stellar.org".to_string()).unwrap();
+        let horizon_client = HorizonClient::new("https://horizon-testnet.stellar.org").unwrap();
 
         // construct request
         let accounts_request = AccountsRequest::new()
@@ -156,8 +155,7 @@ pub mod test {
     #[tokio::test]
     async fn test_get_single_account() {
         // Initialize horizon client
-        let horizon_client =
-            HorizonClient::new("https://horizon-testnet.stellar.org".to_string()).unwrap();
+        let horizon_client = HorizonClient::new("https://horizon-testnet.stellar.org").unwrap();
 
         // construct request
         let single_account_request = SingleAccountRequest::new()

diff --git a/stellar_rust_sdk/src/assets/all_assets_request.rs b/stellar_rust_sdk/src/assets/all_assets_request.rs
@@ -20,7 +20,7 @@ use stellar_rust_sdk_derive::pagination;
 /// # use stellar_rs::horizon_client::HorizonClient;
 /// #
 /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
-/// # let base_url = "https://horizon-testnet.stellar.org".to_string();
+/// # let base_url = "https://horizon-testnet.stellar.org";
 /// # let horizon_client = HorizonClient::new(base_url)
 /// #    .expect("Failed to create Horizon Client");
 /// #

diff --git a/stellar_rust_sdk/src/assets/mod.rs b/stellar_rust_sdk/src/assets/mod.rs
@@ -102,8 +102,7 @@ pub mod test {
         static AUTH_CLAWBACK_ENABLED: &bool = &false;
 
         // Initialize horizon client
-        let horizon_client =
-            HorizonClient::new("https://horizon-testnet.stellar.org".to_string()).unwrap();
+        let horizon_client = HorizonClient::new("https://horizon-testnet.stellar.org").unwrap();
 
         // construct request
         let all_assets_request: AllAssetsRequest = AllAssetsRequest::new().set_limit(1).unwrap();

diff --git a/stellar_rust_sdk/src/claimable_balances/mod.rs b/stellar_rust_sdk/src/claimable_balances/mod.rs
@@ -163,8 +163,7 @@ mod tests {
         static CLAWBACK_ENABLED: &bool = &false;
 
         // Initialize horizon client
-        let horizon_client =
-            HorizonClient::new("https://horizon-testnet.stellar.org".to_string()).unwrap();
+        let horizon_client = HorizonClient::new("https://horizon-testnet.stellar.org").unwrap();
 
         // construct request
         let all_claimable_balances_request =
@@ -217,8 +216,7 @@ mod tests {
             "9234-00000000fe3d8209ed9662e92f0d3a5c55068e18bd5e0697c3c6db6ac4c0870c6f3e0b38";
 
         // Initialize horizon client
-        let horizon_client =
-            HorizonClient::new("https://horizon-testnet.stellar.org".to_string()).unwrap();
+        let horizon_client = HorizonClient::new("https://horizon-testnet.stellar.org").unwrap();
 
         let single_claimable_balance_request = SingleClaimableBalanceRequest::new()
             .set_claimable_balance_id(CLAIMABLE_BALANCE_ID.to_string());

diff --git a/stellar_rust_sdk/src/claimable_balances/single_claimable_balance_request.rs b/stellar_rust_sdk/src/claimable_balances/single_claimable_balance_request.rs
@@ -31,7 +31,7 @@ pub struct NoClaimableBalanceId;
 /// # use stellar_rs::models::Request;
 /// #
 /// # async fn fetch_single_claimable_balance() -> Result<(), Box<dyn std::error::Error>> {
-/// #     let horizon_client = HorizonClient::new("https://horizon-testnet.stellar.org".to_string())?;
+/// #     let horizon_client = HorizonClient::new("https://horizon-testnet.stellar.org")?;
 /// let request = SingleClaimableBalanceRequest::new()
 ///     .set_claimable_balance_id("00000000".to_string());  // Example claimable balance ID
 ///

diff --git a/stellar_rust_sdk/src/effects/mod.rs b/stellar_rust_sdk/src/effects/mod.rs
@@ -128,8 +128,7 @@ mod tests {
 
     #[tokio::test]
     async fn test_get_all_effects() {
-        let horizon_client =
-            HorizonClient::new("https://horizon-testnet.stellar.org".to_string()).unwrap();
+        let horizon_client = HorizonClient::new("https://horizon-testnet.stellar.org").unwrap();
 
         let num_records_to_fetch = 2;
 
@@ -174,8 +173,7 @@ mod tests {
         const CREATED_AT: &str = "2024-06-11T21:36:12Z";
         const STARTING_BALANCE: &str = "10000000000.0000000";
         // Initialize horizon client
-        let horizon_client =
-            HorizonClient::new("https://horizon-testnet.stellar.org".to_string()).unwrap();
+        let horizon_client = HorizonClient::new("https://horizon-testnet.stellar.org").unwrap();
 
         let effects_for_account_request = EffectsForAccountRequest::new().set_limit(2).unwrap();
 
@@ -209,8 +207,7 @@ mod tests {
         const CREATED_AT: &str = "2024-06-11T21:36:12Z";
         const STARTING_BALANCE: &str = "10000000000.0000000";
 
-        let horizon_client =
-            HorizonClient::new("https://horizon-testnet.stellar.org".to_string()).unwrap();
+        let horizon_client = HorizonClient::new("https://horizon-testnet.stellar.org").unwrap();
 
         let effects_for_liquidity_pools_request =
             EffectsForLiquidityPoolRequest::new().set_limit(2).unwrap();
@@ -258,8 +255,7 @@ mod tests {
         const CREATED_AT: &str = "2024-06-11T22:16:55Z";
         const STARTING_BALANCE: &str = "0.0000000";
 
-        let horizon_client =
-            HorizonClient::new("https://horizon-testnet.stellar.org".to_string()).unwrap();
+        let horizon_client = HorizonClient::new("https://horizon-testnet.stellar.org").unwrap();
 
         let effects_for_ledger_request =
             EffectsForLedgerRequest::new().set_sequence(LEDGER_SEQUENCE);
@@ -297,8 +293,7 @@ mod tests {
         const CREATED_AT: &str = "2024-06-11T21:36:12Z";
         const STARTING_BALANCE: &str = "10000000000.0000000";
 
-        let horizon_client =
-            HorizonClient::new("https://horizon-testnet.stellar.org".to_string()).unwrap();
+        let horizon_client = HorizonClient::new("https://horizon-testnet.stellar.org").unwrap();
 
         let effects_for_operation_request = EffectsForOperationRequest::new()
             .set_operation_id(OPERATION_ID)
@@ -337,8 +332,7 @@ mod tests {
         const CREATED_AT: &str = "2024-06-11T21:36:12Z";
         const STARTING_BALANCE: &str = "10000000000.0000000";
 
-        let horizon_client =
-            HorizonClient::new("https://horizon-testnet.stellar.org".to_string()).unwrap();
+        let horizon_client = HorizonClient::new("https://horizon-testnet.stellar.org").unwrap();
 
         let effects_for_transaction_request = EffectForTransactionRequest::new()
             .set_transaction_hash(TRANSACTION_HASH.to_string())

diff --git a/stellar_rust_sdk/src/fee_stats/mod.rs b/stellar_rust_sdk/src/fee_stats/mod.rs
@@ -38,8 +38,7 @@ mod tests {
 
     #[tokio::test]
     async fn test_get_fee_stats() {
-        let horizon_client =
-            HorizonClient::new("https://horizon-testnet.stellar.org".to_string()).unwrap();
+        let horizon_client = HorizonClient::new("https://horizon-testnet.stellar.org").unwrap();
 
         let fee_stats_request = FeeStatsRequest::new();
         let fee_stats_response = horizon_client.get_fee_stats(&fee_stats_request).await;