Update docs introduction (#368)

* update the docs structure

* minor docs tweaking

* update design space docs

* fix self-hosted mermaid diagram

* Rename mermaid item

docs/book.toml

@@ -3,7 +3,7 @@ authors = ["cyberhoward"]
 language = "en"
 multilingual = false
 src = "src"
-title = "Abstract SDK"
+title = "Abstract Development Platform"
 
 
 [build]

docs/src/intro.md → docs/src/1_intro.md

@@ -5,17 +5,17 @@
 
 <div align="center">
 
-### Welcome to Abstract, the interchain CosmWasm development platform. We're building the tools and infrastructure that are required to truly innovate in the Cosmos ecosystem.
+### Welcome to Abstract, the interchain CosmWasm development platform. We are building tools and infrastructure for the next generation of smart-contract applications.
 
 </div>
 
-## What is Abstract?
+## What Is The Abstract Platform?
 
 The Abstract platform is a combination of CosmWasm tooling, on-chain smart-contract infrastructure and front-end libraries. It's designed to be modular, allowing developers to choose the components they need to build their applications. While Abstract tries to simplify a lot of the development experience, it is inherently a power-tool, allowing you to get more done with less effort.
 
 ### The Abstract SDK
 
-The Abstract SDK is a modular smart-contract framework designed to enhance the development of CosmWasm dApps. It's built on top of CosmWasm; a battle-tested WASM-based smart-contract framework.
+The Abstract SDK is a modular smart-contract framework designed to enhance the development of CosmWasm dApps. It's built on top of CosmWasm; a battle-tested WASM-based smart-contract framework, written in Rust.
 
 Here's a small snippet of code to give you an idea of what using the Abstract SDK looks like:
 
@@ -25,15 +25,15 @@ Here's a small snippet of code to give you an idea of what using the Abstract SD
 
 The code above defines an Abstract app, which is a smart-contract that can be installed on any Abstract Account. The app has a unique ID and a version, both are used to offer the app on the Abstract App store, allowing other users to install the app on their account.
 
-The App object is made available within the customizable handlers. This object is highly programmable through the [abstract-sdk](./get_started/sdk.md), which is our Account Abstraction Toolbox. In a nutshell it allows you to perform complex multi-contract interactions with very minimal code while not compromising on the contract's programmability in any way.
+The customizable handlers allow for full developer freedom and have an App object available within them. This object is highly programmable through the [abstract-sdk](./get_started/sdk.md), which is our Account Abstraction Toolbox. In a nutshell it allows you to perform complex multi-contract interactions with very minimal code while not compromising on the contract's programmability in any way.
 
-> Looking to get started? Check out the [Getting Started](./get_started/index.md) guide.
+> Looking to get started? Check out the [Getting Started](./3_get_started/1_index.md) guide.
 
 ### Cw-Orchestrator
 
-[cw-orchestrator](https://github.com/AbstractSDK/cw-orchestrator) is the tool that makes developing with Abstract so pleasant. It's a smart-contract scripting library that allows you to re-use code for use in testing and deployments. It's also our primary tool for making Abstract's infrastructure highly available.
+[cw-orchestrator](https://github.com/AbstractSDK/cw-orchestrator) is a smart-contract scripting library that allows you to re-use code for use in testing and deployments. It is also our primary tool for making Abstract's infrastructure highly available allowing us to make developing with Abstract a pleasant experience.
 
-Here's a snippet that sets up the complete Abstract framework on a cw-multi-test environment, and deploys the previously shown App contract to the framework.
+Here's a snippet that sets up the complete Abstract framework on a cw-multi-test environment and deploys the previously shown App contract to the framework.
 
 ```rust,no_run
 // Create a sender and instantiate the mock environment
@@ -63,10 +63,12 @@ abstr_deployment
 contract.deploy(APP_VERSION.parse()?)?;
 ```
 
-Using cw-orchestrator reduces your testing setup and complexity and improves both the code's readability and maintainability. Because of its design it allows us to share our contracts with any developer that wants to use them with a few lines of code. This greatly reduces the friction of using our code and it allows you to provide the same experience to developers that might want to use your code, giving you an edge over other options.
+Using cw-orchestrator for your testing and deployment needs reduces your testing setup and complexity and improves both the code's readability and maintainability. Because of its design it allows us to share our contracts with any developer that wants to use them with a few lines of code. This greatly reduces the friction of using our code and it allows you to provide the same experience to developers that might want to use your code, giving you an edge over other options.
 
 ## Abstract.js
 
+Abstract.js is the Javascript package for interacting with the on-chain Abstract framework.
+
 <!-- ## Features
 
 - Chain-Agnostic: The Abstract platform is built to support various blockchain networks within the Cosmos ecosystem, giving developers the flexibility to choose the best-suited platform for their dApp.

docs/src/2_introduction/1_design_space.md

@@ -0,0 +1,66 @@
+# The Abstract SDK Design Space
+
+The first step to using a tool is learning its purpose and capabilities. Working with the Abstract SDK is no different. This page will help you understand the design space that the Abstract SDK operates in, which will help you reason about how to use the SDK effectively.
+
+## Design Space
+
+The Abstract SDK design space is a superset of the classical smart-contract design space, meaning that any application built with stand-alone smart-contracts can be implemented with the SDK as well. However, Abstract's design space is unique in that it allows for a level of code re-usability that would not be possible with stand-alone smart-contracts. By thinking about on-chain functionality in a functional sense, we created a system where application development can be done in a more conceptual way.
+
+Additionally the SDK allows for software distribution that is unparalleled in the smart-contract space. With the Abstract SDK you can write your code once, deploy it to any blockchain that supports CosmWasm and let other developers **and users** use it within minutes. This opens up the possibility of creating a marketplace for smart-contracts, where developers can sell their code to other developers and users in a permissionless way.
+
+This section will give you a high-level overview of the different approaches and how they can be used to build your application.
+
+### Hosted Applications
+
+Hosted applications are traditionally applications that are built using stand-alone smart-contracts. Examples of these types of applications are dexes, lending markets, yield aggregators, etc. What makes these applications *hosted* is that they are deployed by the maintainers of the application and often require the user to transfer funds to the application's smart-contract in order to use it.
+
+```mermaid
+flowchart LR
+    subgraph Developer Team [fas:fa-users-cog Developer Team]
+        %% subgraph Application
+            direction BT
+            A[Application]
+        %% end
+    end
+
+    User[fa:fa-users Users]==>A
+
+```
+
+### Self-Hosted Applications
+
+By self-hosted applications we mean applications that are **fully** owned by the user. This means that the user does not have to transfer funds to the application's smart-contract in order to use it. Instead the user can deploy the application's smart-contract to their own account and use it from there. This is a novel concept that is only possible with the Abstract SDK.
+
+```mermaid
+flowchart LR
+    subgraph Developers [fas:fa-users-cog Developers]
+            direction RL
+            A[App]
+    end
+
+    subgraph Acc1 [fas:fa-user User's Account]
+        direction TB
+        Ap1[App]-->A1[Account]
+    end
+
+    subgraph Acc2 [fas:fa-user User's Account]
+        direction TB
+        Ap2[App]-->A2[Account]
+    end
+
+    subgraph Acc3 [fas:fa-user User's Account]
+        direction TB
+        Ap3[App]-->A3[Account]
+    end
+
+        Store-.->Ap1
+        Store-.->Ap2
+        Store-.->Ap3
+
+    A==>Store[fa:fa-store App Store]
+```
+
+This two main benefits:
+
+- **Sovereignty:** There are less trust assumptions that the user has to make. The user does not have to trust the application's maintainers to not steal their funds.
+- **Customizability:** The user can customize the application to their liking. Applications that take this design in mind can provide novel customization options that would not be possible with hosted applications.

docs/src/get_started/index.md → docs/src/3_get_started/1_index.md

@@ -1,10 +1,8 @@
 # Abstract SDK - How to get started
 
-So you want to build on Abstract? Let's get your idea shipped!
+This tutorial will walk you through the process of setting up your development environment, creating an [app module](../4_framework/7_module_types.md#apps), and deploying your first app to our on-chain store with [cw-orchestator](https://github.com/AbstractSDK/cw-orchestrator).
 
-This tutorial will walk you through the process of setting up your development environment, creating an [app module](../framework/module_types.md#apps), and deploying your first app to our on-chain store with [cw-orchestator](https://github.com/AbstractSDK/cw-orchestrator).
-
-If you want to learn more about Abstract before writing code you can check out the [*About Abstract*](../framework/abstract_sdk.md) section of our documentation.
+If you want to learn more about Abstract before writing code you can check out the [*About Abstract*](../4_framework/1_abstract_sdk.md) section of our documentation.
 
 ## Prerequisites
 

docs/src/4_framework/1_abstract_sdk.md

@@ -0,0 +1,47 @@
+# Abstract SDK - Overview
+
+The Abstract SDK is at the core of the Abstract development platform. It's a modular smart-contract framework designed to simplify and accelerate the development of CosmWasm dApps. It does this by prioritizing re-usability and composability through an account-abstraction oriented architecture.
+
+From a high-level perspective, smart-contracts built with abstract can use on-chain dependencies (other smart-contracts) to isolate specific functionalities. In this way a smart-contract built with the Abstract SDK can explicitly define its dependencies and use them to perform complex multi-contract interactions with very minimal code. This in turn allows you to focus on the novel functionality of your application without inheriting the complexity of the underlying infrastructure.
+
+## Visual Example
+
+Visually this can be represented as an application, for example an `Autocompounder`, that has a dependency on one or multiple other smart-contracts. In this case a `Dex` and `Staking` module.
+
+```mermaid
+flowchart LR
+    subgraph Autocompounder Application
+        direction BT
+        Autocompounder-.->Dex
+        Autocompounder-.->Staking
+        Staking-->Account
+        Autocompounder-->Account
+        Dex-->Account
+    end
+
+    User[fa:fa-users Users]==>Autocompounder
+```
+
+Each full arrow signifies execution permissions of the contract on the account. It allows the contract to move funds, interact with other contracts through the account and perform other actions. It does this by sending messages to the account, which then executes them on behalf of the contract. This is the basic idea behind account abstraction and is further elaborated in on the [account abstraction](./3_account_abstraction.md) page.
+
+Each dotted arrow indicates a dependency between the contracts. These dependencies are explicitly defined in the contract and are asserted at contract instantiation. In this example the autocompounder contract is able to access specific functionality (like swapping or staking assets) from its dependencies (the dex and staking contracts). Through this a major reduction in code complexity and size is achieved as otherwise every dex or yield provider would have to be integrated with the autocompounder contract itself.
+
+From a developer ecosystem standpoint this encourages collaboration and cross-team code re-use, a practice that has been proven to accelerate development and increase productivity. As the saying goes, a rising tide lifts all boats.
+
+<!-- ## What Problem Does it Solve?
+
+The Abstract SDK is designed to solve the following problems:
+
+- **Reusability:** CosmWasm development has been a start-from-scratch process up until now. The Abstract SDK allows developers to reuse components across multiple dApps, reducing development time, increasing productivity, iteration speed and shortening the go-to-market of your ideas.
+
+- **Security:** The Abstract SDK is built on top of the CosmWasm smart-contract framework, which is a battle-tested and highly secure platform. Because of its modular design, it's also easier to audit and test. Audited components can be reused across multiple dApps, reducing the risk of bugs and vulnerabilities.
+
+- **Complexity:** The Abstract SDK simplifies the development process by providing a modular framework that allows developers to focus on the core functionality of their dApp.
+
+- **Compatibility:** The Abstract SDK is designed to work seamlessly with popular on-chain services in the Cosmos ecosystem, decentralized exchanges, money markets, oracles, etc.
+
+- **Interoperability:** The Abstract SDK is chain-agnostic, allowing developers to build dApps that can interact with multiple blockchains within the Cosmos ecosystem.
+
+- **Scalability:** The Abstract SDK is designed to scale with the needs of the developer, allowing them to easily deploy to new networks, iterate on their product and achieve product market fit. Through its novel on-chain application store it also allows for personalized dApps that can be customized by the user to meet their specific needs, making the Abstract SDK the first decentralized software distribution platform.
+
+- **Collaboration:** The Abstract SDK enables developers to collaborate on the creation of dApps its composable architecture and the ability to easily publish testing infrastructure for mock environment construction. -->

docs/src/framework/actor_model.md → docs/src/4_framework/2_actor_model.md

@@ -1,16 +1,16 @@
 # The Actor Model
 
-The actor model is a computational model used in the design and implementation of CosmWasm smart contracts. It provides a secure and deterministic execution environment by employing message-based communication between individual actors. In this model, actors are autonomous entities capable of making local decisions, creating more actors, and responding to incoming messages. This model ensures encapsulation, concurrency control, and fault tolerance in distributed systems.
+The actor model is a computational model used in the design and implementation of CosmWasm smart contracts. It provides a deterministic execution environment by employing message-based communication between individual actors. In this model, each actor is an autonomous entity capable of making local decisions (managing state), creating more actors (other smart-contracts), and responding to incoming messages.
 
-In CosmWasm, the actor model plays a crucial role in the architecture of smart contracts. The actor model helps ensure the following key principles within CosmWasm:
+In CosmWasm, the actor model plays a crucial role in designing the architecture of a smart contract application. The actor model ensures that the following key principles hold within CosmWasm:
 
 ### 1. Encapsulation and Isolation
 
-Each smart contract operates as an isolated actor, processing messages independently. This isolation prevents interference and unintended side effects between contracts, enhancing security and reducing the risk of vulnerabilities like reentrancy attacks.
+Each smart contract operates as an isolated actor, processing messages independently. This isolation prevents interference and unintended side effects between contracts, enhancing security and reducing the risk of vulnerabilities like re-entrancy attacks.
 
 ### 2. Sequential Message Processing
 
-Contracts can handle only one message at a time, ensuring deterministic execution and eliminating the need for call stacks. This approach prevents complex control flow issues and helps maintain the integrity of contract state.
+Contracts can handle only one message at a time, ensuring deterministic execution and eliminating the need for call stacks. This approach prevents complex control flow issues and helps maintain the integrity of contract state. It also simplifies the mental model required to understand and reason about execution order in multi-contract interactions.
 
 ### 3. Controlled Interactions
 
@@ -20,9 +20,9 @@ When a contract wants to invoke another contract, it sends a message containing
 
 A top-level message in CosmWasm represents a transaction that encompasses multiple sub-messages. If any sub-message encounters an error, the entire transaction is rolled back, reverting all state changes made within that transaction. This ensures atomicity and prevents inconsistent states in the contract
 
-## Relevance to the Abstract Account
+## Relevance to the Abstract SDK
 
-In the context of Abstract Accounts each smart-contract acts as an independent actor provides distinct benefits.
+In the context of the Abstract SDK each smart-contract
 
 ### Enhanced Security through State Isolation