Improve build section

docs/build/README.mdx

@@ -1,26 +1,45 @@
 ---
 title: "Get Started with Blockchain Development; Guides, Tutorials & Tools"
 sidebar_label: Introduction
+icon: "house"
 sidebar_position: 0
-hide_table_of_contents: true
+hide_table_of_contents: false
 description: "Get started with developing on the Stellar with guides, tutorials, tools, and resources. Learn how to write smart contracts, build applications, and more."
 ---
 
 # Introduction
 
-The Build section is split into three parts: 1) writing smart contracts, 2) building applications, and 3) how-to guides.
+The Build section is split into three parts:
 
-Find explanations on what each section contains below.
+1. [Smart contracts](/docs/build/smart-contracts)
+2. [Applications](/docs/build/apps)
+3. [How-to guides](/docs/build/guides)
+
+Explanations for each section are stated below:
 
 ## Smart contracts
 
-Smart contracts are self-executing programs with the terms of an agreement written directly into the code. They automatically enforce and execute the terms of the contract when predefined conditions are met. Developers must define the rules and logic of the contract while also ensuring security. Once written and tested, smart contracts are deployed to the blockchain, where they become immutable and publicly accessible.
+Smart contracts are self-executing programs with the terms of an agreement written directly into the code. They automatically enforce and execute the terms of the contract when predefined conditions are met. Once written and tested, smart contracts are deployed to the blockchain, where they become immutable and publicly accessible.
+
+:::tip
+
+While defining the rules and logic of the contract, developers must be security conscious to avoid vulnerabilities such as integer overflows, access control flaws, and other exploits that could compromise the integrity and functionality of the smart contract.
 
-This section will walk you through how to get set up to write smart contracts on Stellar, plus an introduction to testing, storing data, and deploying your contracts. It also provides an array of example contracts for use.
+:::
+
+This section will walk you through how to write and deploy smart contracts on Stellar, including the installation process, an introduction to testing, storing data, and more. It also provides a variety of example contracts for reference and use.
 
 ## Applications
 
-Applications interact with the blockchain and can use smart contracts as the backend. They provide user interfaces, manage user interactions, and can integrate with smart contracts to operate. Users can interact with the blockchain using the application interface. Writing smart contracts focuses on the backend logic and rules enforced on the blockchain while building applications involves creating the front end and integrating it with these smart contracts to provide a complete user experience.
+Applications interact with the blockchain and can use smart contracts as the backend.
+
+They:
+
+- Provide user interfaces (UI);
+- Manage user interactions;
+- Integrate with smart contracts to operate.
+
+Writing **smart contracts** focuses on the backend logic and rules enforced on the blockchain, while **building applications** involves creating the frontend and integrating it with these smart contracts to provide a complete user experience.
 
 :::note
 
@@ -30,8 +49,12 @@ You can create applications on Stellar without using smart contracts, as demonst
 
 This section walks you through design considerations for applications and tutorials for building applications with or without smart contracts.
 
-## How-To Guides
+## How-to guides
+
+This section provides step-by-step instructions to help users complete specific tasks associated with building on Stellar. These tasks can include instructions for aspects of writing contracts, interacting with contracts, building applications, using Stellar operations, setting up infrastructure, and more.
 
-This section provides step-by-step instructions to help users complete specific tasks associated with developing on Stellar. These tasks can include instructions for aspects of writing contracts, interacting with contracts, building applications, using Stellar operations, setting up infrastructure, and more.
+:::note
 
 How-to guides assume that the user has some experience and knowledge with building on Stellar and are not typically for beginners.
+
+:::

docs/build/smart-contracts/getting-started/setup.mdx

@@ -18,7 +18,7 @@ import { StellarCliWingetVersion } from "@site/src/components/StellarCliWingetVe
 
 Stellar smart contracts are small programs written in the [Rust] programming language.
 
-To build and develop contracts you need only a couple prerequisites:
+To build and develop contracts you need the following prerequisites:
 
 - A [Rust] toolchain
 - An editor that supports Rust
@@ -70,25 +70,25 @@ Install the `wasm32-unknown-unknown` target.
 rustup target add wasm32-unknown-unknown
 ```
 
-## Configure an Editor
+## Configure an editor
 
 Many editors have support for Rust. Visit the following link to find out how to configure your editor: https://www.rust-lang.org/tools
 
-A popular editor is Visual Studio Code:
+Here are the tools to you need to configure your editor:
 
-- [Visual Studio Code] editor.
-- [Rust Analyzer] for Rust language support.
-- [CodeLLDB] for step-through-debugging.
-
-[visual studio code]: https://code.visualstudio.com
-[rust analyzer]: https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer
-[codelldb]: https://marketplace.visualstudio.com/items?itemName=vadimcn.vscode-lldb
+1. [Visual Studio Code](https://code.visualstudio.com) as code editor (or another code editor that supports Rust)
+2. [Rust Analyzer](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer) for Rust language support
+3. [CodeLLDB](https://marketplace.visualstudio.com/items?itemName=vadimcn.vscode-lldb) for step-through-debugging
 
 ## Install the Stellar CLI
 
 The [Stellar CLI](https://github.com/stellar/stellar-cli) can execute smart contracts on futurenet, testnet, mainnet, as well as in a local sandbox.
 
-The latest stable release is [v{latestVersion}](https://github.com/stellar/stellar-cli/releases/latest).
+:::info
+
+The latest stable release is [v22.6.0](https://github.com/stellar/stellar-cli/releases/latest).
+
+:::
 
 ### Install
 

docs/build/smart-contracts/overview.mdx

@@ -7,68 +7,132 @@ description: "An overview of Stellar smart contracts, including information abou
 
 # Overview
 
-Soroban is the smart contracts platform on the Stellar network. Contracts are small programs written in the [Rust programming language](https://www.rust-lang.org/) and compiled as WebAssembly (Wasm) for deployment.
+Soroban is the smart contracts platform on the Stellar network. These contracts are small programs written in the [Rust language](https://www.rust-lang.org/) and compiled as [WebAssembly](https://webassembly.org/) (Wasm) for deployment.
 
-To begin writing contracts, [install a Rust toolchain](https://www.rust-lang.org/tools/install), configure your [editor to support Rust programs](https://www.rust-lang.org/tools), and [learn some basic Rust concepts](https://www.rust-lang.org/learn).
+To begin writing contracts, you must have:
 
-## Rust on Stellar
-
-Stellar smart contracts have several characteristics (such as resource limits, security considerations, and more) that force contracts to use only a narrow subset of the full Rust language and must use specialized libraries for most tasks. Read more in the [Contract Rust Dialect section](../../learn/encyclopedia/contract-development/rust-dialect.mdx).
-
-In particular, the Rust standard library and most third-party libraries (called “crates”) will not be available for direct off-the-shelf use in contracts due to the abovementioned constraints. Some crates can be adapted for use in contracts, and others may be incorporated into the host environment as host objects or functions.
-
-Support for other languages may be supported in the future, but at this time, only Rust is supported.
-
-## Soroban Rust SDK
-
-Contracts are developed using a software development kit (SDK). The [Soroban Rust SDK](../../tools/sdks/contract-sdks.mdx#soroban-rust-sdk) consists of a Rust crate and a command-line tool.
-
-The SDK crate acts as a substitute for the Rust standard library — providing data structures and utility functions for contracts — as well as providing access to smart-contract-specific functionality from the contract environment, like cryptographic hashing and signature verification, access to on-chain persistent storage, and location and invocation of secondary contracts via stable identifiers.
-
-The Soroban SDK command-line tool provides a developer-focused front-end for compiling, testing, inspecting, versioning, and deploying contracts. It also includes a complete implementation of the contract host environment that is identical to the one that runs on-chain, called **local testing mode**. With this capability, contracts can be run locally on a developer's workstation and can be [tested and debugged] directly with a local debugger within a standard IDE, as well as a native test harness for fast-feedback unit testing and high-speed fuzzing or property testing.
-
-## Host environment
+1. [Install a Rust toolchain](https://www.rust-lang.org/tools/install)
+2. Configure your [editor to support Rust programs](https://www.rust-lang.org/tools)
+3. [Learn some basic Rust concepts](https://www.rust-lang.org/learn)
 
-The host environment is a set of Rust crates compiled into the SDK command-line tool and stellar-core. It comprises a set of host objects and functions, an interface to on-chain storage and contract invocation, a resource-accounting and fee-charging system, and a Wasm interpreter.
-
-Most contract developers will not frequently need to interact with the host environment directly — SDK functions wrap most of its facilities and provide richer and more ergonomic types and functions — but it is helpful to understand its structure to understand the conceptual model the SDK is presenting. Some parts of the host environment will likely be visible when testing or debugging contracts compiled natively on a local workstation.
-
-Read more in the [Environment Concepts section](../../learn/encyclopedia/contract-development/environment-concepts.mdx).
-
-## Soroban FAQs
+## Rust on Stellar
 
-**What is Soroban to Stellar? Is it a new blockchain?​**
+Stellar smart contracts have several characteristics (such as resource limits, security considerations, and more) that force contracts to use only a narrow subset of the full Rust language and must use specialized libraries for most tasks.
 
-Soroban is not a new blockchain. Soroban is a smart contract platform integrated into the existing Stellar blockchain. It is an additive feature that lives alongside and doesn't replace the existing set of Stellar operations.
+Learn more in the [Contract Rust Dialect section](../../learn/encyclopedia/contract-development/rust-dialect.mdx).
 
-**How do I invoke a Soroban contract on Stellar?​**
+In particular, the Rust standard library and most third-party libraries (called [crates](../../learn/migrate/evm/solidity-and-rust-advanced-concepts#crates)) will not be available for direct off-the-shelf use in contracts due to the abovementioned constraints. Some crates can be adapted for use in contracts, and others may be incorporated into the host environment as host objects or functions.
 
-Invoke a Soroban contract by submitting a transaction that contains the new operation: [`InvokeHostFunctionOp`](../../learn/fundamentals/transactions/list-of-operations.mdx#invoke-host-function).
+:::note
 
-**Can Soroban contracts use Stellar accounts for authentication?​**
+Other languages may be supported in the future, but at this time, only Rust is supported.
 
-Yes. Stellar accounts are shared with Soroban. Smart contacts have access to Stellar account signer configuration and know the source account that directly invoked them in a transaction. Check out the [Authorization section](../../learn/encyclopedia/security/authorization.mdx) for more information.
+:::
 
-**Can Soroban contracts interact with Stellar assets?​**
+## Soroban Rust SDK
 
-Yes. Soroban contains a built-in [Stellar Asset Contract](../../tokens/stellar-asset-contract.mdx) that can interact with classic trustlines.
+Contracts are developed using a software development kit (SDK). The [Soroban Rust SDK](../../tools/sdks/contract-sdks.mdx#soroban-rust-sdk) consists of a Rust crate and a command-line (CLI) tool.
 
-**Do issuers of Stellar assets maintain authorization over an asset sent to a non-account identifier in Soroban (`AUTH_REQUIRED`, `AUTH_REVOCABLE`, `AUTH_CLAWBACK`)​?**
+The SDK crate acts as a substitute for the Rust standard library — providing data structures and utility functions for contracts — as well as providing access to smart-contract-specific functionality from the contract environment, like cryptographic hashing and signature verification, access to on-chain persistent storage, and location and invocation of secondary contracts via stable identifiers.
 
-Yes. Issuers retain the same level of control on Soroban as they have regularly. This functionality is accessible through a set of admin functions (clawback, set_auth) on the built-in Stellar Asset Contract.
+The Soroban SDK CLI tool provides a developer-focused front-end for:
 
-**Can Soroban contracts interact with any other Stellar operations?​**
+- Compiling
+- Testing
+- Inspecting
+- Versioning
+- Deploying
 
-No. Aside from the interactions with accounts and assets mentioned above. This means that Soroban contracts cannot interact with the SDEX, claimable balances, or sponsorships.
+It also includes a complete implementation of the contract host environment that is identical to the one that runs on-chain, called [local testing mode](/docs/learn/encyclopedia/errors-and-debugging/debugging#local-testing-mode). With this capability, contracts can be run locally on a developer's workstation and can be tested and debugged directly with a local debugger within a standard IDE, as well as a native test harness for fast-feedback unit testing and high-speed fuzzing or property testing.
 
-**Does the Stellar base reserve apply to Soroban contracts?​**
+## Host environment
 
-No. Soroban has a different [fee structure](../../learn/fundamentals/fees-resource-limits-metering.mdx), and ledger entries that are allocated by Soroban contracts do not add to an account's required minimal balance.
+The host environment is a set of Rust crates compiled into the SDK CLI tool and stellar-core. It comprises a set of host objects and functions, an interface to on-chain storage and contract invocation, a resource-accounting and fee-charging system, and a Wasm interpreter.
 
-**Should I issue my token as a Stellar asset or a custom Soroban token?​**
+Most contract developers will not frequently need to interact with the host environment directly — SDK functions wrap most of its facilities and provide richer and more ergonomic types and functions — but it is helpful to understand its structure to understand the conceptual model the SDK is presenting. Some parts of the host environment will likely be visible when testing or debugging contracts compiled natively on a local workstation.
 
-To the greatest extent possible, we recommend issuing tokens as Stellar assets. These tokens will benefit from being interoperable with the existing tools available in the Stellar ecosystem and are more performant because the Stellar Asset Contract is built into the host. Read more in the [Tokens Overview](../../tokens/README.mdx).
+Learn more in the [Environment Concepts section](../../learn/encyclopedia/contract-development/environment-concepts.mdx).
 
-**Need help finding what you're looking for?​**
+## Soroban FAQs
 
-Ask in the Developer channels in the [Stellar Developer Discord](https://discord.gg/stellardev).
+<!-- prettier-ignore-start -->
+<details>
+  <summary>
+   **What is Soroban to Stellar? Is it a new blockchain?​**
+  </summary>
+  Soroban is not a new blockchain. Soroban is a smart contract platform
+  integrated into the existing Stellar blockchain. It is an additive feature
+  that lives alongside and doesn't replace the existing set of Stellar
+  operations.
+</details>
+<details>
+  <summary>
+   **How do I invoke a Soroban contract on Stellar?​**
+  </summary>
+  Invoke a Soroban contract by submitting a transaction that contains the new
+  operation:
+  [`InvokeHostFunctionOp`](../../learn/fundamentals/transactions/list-of-operations.mdx#invoke-host-function).
+</details>
+<details>
+  <summary>
+    **Can Soroban contracts use Stellar accounts for authentication?​**
+  </summary>
+  Yes. Stellar accounts are shared with Soroban. Smart contacts have access to
+  Stellar account signer configuration and know the source account that directly
+  invoked them in a transaction. Check out the [Authorization
+  section](../../learn/encyclopedia/security/authorization.mdx) for more
+  information.
+</details>
+<details>
+  <summary>
+   **Can Soroban contracts interact with Stellar assets?​**
+  </summary>
+  Yes. Soroban contains a built-in [Stellar Asset
+  Contract](../../tokens/stellar-asset-contract.mdx) that can interact with
+  classic trustlines.
+</details>
+<details>
+  <summary>
+    **Do issuers of Stellar assets maintain authorization over an asset sent to
+    a non-account identifier in Soroban (`AUTH_REQUIRED`, `AUTH_REVOCABLE`,
+    `AUTH_CLAWBACK`)​?**
+  </summary>
+  Yes. Issuers retain the same level of control on Soroban as they have
+  regularly. This functionality is accessible through a set of admin functions
+  (clawback, set_auth) on the built-in Stellar Asset Contract.
+</details>
+<details>
+  <summary>
+    **Can Soroban contracts interact with any other Stellar operations?​**
+  </summary>
+  No. Aside from the interactions with accounts and assets mentioned above. This
+  means that Soroban contracts cannot interact with the SDEX, claimable
+  balances, or sponsorships.
+</details>
+<details>
+  <summary>
+    **Does the Stellar base reserve apply to Soroban contracts?​**
+  </summary>
+  No. Soroban has a different [fee
+  structure](../../learn/fundamentals/fees-resource-limits-metering.mdx), and
+  ledger entries that are allocated by Soroban contracts do not add to an
+  account's required minimal balance.
+</details>
+<details>
+  <summary>
+   **Need help finding what you're looking for?​**
+  </summary>
+  Ask in the Developer channels in the [Stellar Developer
+  Discord](https://discord.gg/stellardev).
+</details>
+<details>
+  <summary>
+    **Should I issue my token as a Stellar asset or a custom Soroban token?​**
+  </summary>
+  To the greatest extent possible, we recommend issuing tokens as Stellar
+  assets. These tokens will benefit from being interoperable with the existing
+  tools available in the Stellar ecosystem and are more performant because the
+  Stellar Asset Contract is built into the host. Read more in the [Tokens
+  Overview](../../tokens/README.mdx).
+</details>
+<!-- prettier-ignore-end -->

routes.txt

@@ -42,6 +42,7 @@
 /docs/build/guides
 /docs/build/guides/archival
 /docs/build/guides/archival/create-restoration-footprint-js
+/docs/build/guides/archival/extend-persistent-entry-js
 /docs/build/guides/archival/restore-contract-js
 /docs/build/guides/archival/restore-data-js
 /docs/build/guides/archival/test-ttl-extension