docs: enhance wording for Solana pages (#408)

* docs: enhance wording

docs: fix streaming shape names mismatch
docs: fix grammar
docs: fix logical issues
docs: reorganize the Architecture section
docs: change fee representation from USD to SOL
docs: add a paragraph documenting the Metaplex fee
docs: add explanations, where relevant

* refactor: pr review

* chore: wording

* chore: wording

* chore: punctuation

* chore: pr review

* refactor: Architecture & Diagrams

* refactor: ANCHOR_WALLET msg

* refactor: Program Reference

* refactor: metaplex fee

* refactor: stream shapes

* chore: polish points

chore: rename folder name

---------

Co-authored-by: Andrei Vlad Birgaoanu <andreivladbrg@gmail.com>

Author: IaroslavMazur

docs/concepts/lockup/02-stream-shapes.mdx

@@ -6,6 +6,15 @@ title: "Stream Shapes"
 
 :::note
 
+The stream shapes below are examples - and not an exhaustive list.
+
+At the same time, the model for each shape is not a requirement, but a recommendation - for example, the Timelock shape
+can also be implemented via Linear or Dynamic models, but is most efficient with the Tranched model.
+
+:::
+
+:::note
+
 - The code used to generate the gas benchmarks for the different stream curves can be found
   [here](https://github.com/sablier-labs/examples/tree/shapes-benchmark).
 
@@ -33,7 +42,7 @@ The gas cost to create this shape is approximately _168,923_ on Mainnet. This ma
 
 :::
 
-### Initial Unlock
+### Unlock Linear
 
 The Unlock Linear shape combines an initial immediate release of tokens with a steady, linear payout over time. This
 shape is ideal for employment contracts that include a signing bonus along with a regular payout schedule.
@@ -69,7 +78,7 @@ The gas cost to create this shape is approximately _191,182_ on Mainnet. This ma
 
 :::
 
-### Cliff Unlock
+### Cliff
 
 It is possible to attach a "cliff" to a Lockup Linear stream, which sets a cut-off point for releasing tokens. Prior to
 the cliff, the recipient cannot withdraw any tokens, but the stream continues to accrue them. After the cliff, the
@@ -104,7 +113,7 @@ The gas cost to create this shape is approximately _213,708_ on Mainnet. This ma
 
 :::
 
-### Initial Cliff Unlock
+### Unlock Cliff
 
 This shape is useful for companies who want to distribute tokens to their investors using a cliff followed by linear
 vesting but also want to unlock some liquidity at the beginning to be able to allow investors to bootstrap AMM pools.
@@ -206,7 +215,7 @@ The gas cost to create this shape is approximately _274,420_ on Mainnet. This ma
 ## Lockup Tranched
 
 Lockup Tranched streams are, as the name says, streams that have token unlocks in tranches. Even though you can use
-Lockup Dynamic to create a traditional vesting structure with periodic unlocks, Lockup Tranched is specifically design
+Lockup Dynamic to create a traditional vesting structure with periodic unlocks, Lockup Tranched is specifically designed
 for that use case. As a result, a stream with tranches created using Lockup Tranched is more gas efficient than the same
 stream created using Lockup Dynamic.
 

docs/solana/01-sablier-on-solana.md

@@ -29,39 +29,40 @@ available features on Solana.
 
 ## SolSab
 
-[SolSab](https://github.com/sablier-labs/solsab) is a collection of protocols featuring two main Solana programs:
-**Sablier Lockup** and **Sablier Merkle Instant**. While not all protocols available for Ethereum are currently
-available for Solana, we aim to bring the same protocols to Solana in future iterations.
+[SolSab](https://github.com/sablier-labs/solsab) is a collection of Solana protocols currently featuring two programs:
+**Sablier Lockup** and **Sablier Merkle Instant**. While not all of our Ethereum protocols are also available on Solana,
+we aim to bridge this gap in the future.
 
 ### Lockup
 
 Sablier Lockup is a token distribution protocol that enables onchain vesting and payments. Our flagship model is the
 linear stream, which distributes tokens on a continuous, by-the-second basis.
 
-The way it works is that the creator of a payment stream first deposits a specific amount of SPL or Token2022 tokens.
-The program then progressively allocates the funds to the recipient, who can access them as they become available over
-time. The payment rate is influenced by various factors, including the start and end times, as well as the total amount
-of tokens deposited.
+The way it works is that the stream creator first deposits a specific amount of SPL/Token2022 tokens. The program, then,
+progressively transfers the ownership of the funds to the recipient (who can withdraw them as they're streamed). The
+streaming rate is influenced by various factors, such as the start and end times, the total amount of tokens deposited,
+etc.
 
 #### Key differences from the Ethereum [Lockup](../concepts/lockup/01-overview.md) protocol
 
-- The Solana program includes only the Linear streaming model, not the Dynamic and Tranched models. See the available
-  shapes for the Linear model [here](../concepts/lockup/02-stream-shapes.mdx#lockup-linear).
-- Due to the limitations of the [Token Metadata](https://developers.metaplex.com/token-metadata) NFT standard on Solana,
-  we cannot have non-transferable NFTs.
-- Tokens transferred during stream creation are placed in a dedicated Stream ATA
-  ([Associated Token Account](https://www.alchemy.com/overviews/associated-token-account)), instead of all tokens being
-  held in the Lockup contract as on Ethereum.
-- We do not have hooks for the `cancel` and `withdraw` functionalities due to limitations in how Solana works.
+- On Solana, we currently support all shapes from the
+  [Lockup Linear](../concepts/lockup/02-stream-shapes.mdx#lockup-linear) category, as well as the
+  [Timelock](../concepts/lockup/02-stream-shapes.mdx#timelock) shape (also implemented via the Linear program).
+- Due to the limitations of the [Token Metadata](https://developers.metaplex.com/token-metadata) NFT standard, we don't
+  support non-transferable Streams on Solana.
+- Instead of the tokens from all of the streams being stored at a single address, on Solana, they're kept in dedicated
+  stream ATAs ([Associated Token Account](https://www.alchemy.com/overviews/associated-token-account)).
+- Due to how Solana's VM works, we do not support hooks for the `cancel` and `withdraw` functionalities.
 
 ### Merkle Instant
 
-Merkle Instant is a program that enables the creation of token airdrop campaigns using Merkle trees, allowing users to
-instantly claim and receive their allocation through a single transaction.
+The Merkle Instant program enables the creation of Merkle Tree-based token airdrop campaigns that allow users to claim
+their entire allocation at once after the campaign starts.
 
 #### Key differences from the Ethereum [Airdrops](../concepts/05-merkle-airdrops.mdx) protocols
 
-- The Solana program includes only the Instant airdrop model, not the Vesting airdrop models.
-- Due to the nature of Solana's account architecture, we have a single program that handles both the creation and the
-  claiming. In contrast to Ethereum, where we have a factory contract that deploys a stand-alone contract for each
-  airdrop campaign.
+- The Solana protocol only includes the Instant airdrop model, for now. The Vesting airdrop models are coming in the
+  future.
+- Due to Solana’s account architecture, a single program handles both creation and claiming. In contrast to Ethereum,
+  where a factory contract deploys a stand-alone contract for each airdrop campaign, and claiming is performed on that
+  contract.

docs/solana/02-deployment-addresses.md

@@ -4,18 +4,20 @@ sidebar_position: 2
 title: "Deployment Addresses"
 ---
 
-This page contains the deployment addresses for the first SolSab release.
+This page contains the deployment addresses for SolSab.
 
 :::important
 
-Unlike EVM, the programs here adhere to the best practices of Solana development which includes upgradeability.
+SolSab programs adhere to the best practices for Solana development, which includes being upgradeable.
 
 :::
 
 ## Deployment Addresses
 
-All programs are deployed using
-[Anchor's verifiable builds](https://www.anchor-lang.com/docs/references/verifiable-builds) for deterministic bytecode.
+All programs have been built and deployed [verifiably](https://www.anchor-lang.com/docs/references/verifiable-builds),
+generating deterministic bytecode.
+
+### v0.1:
 
 | Chain   | Protocol      | Program ID                                                                                                                             |
 | :------ | :------------ | :------------------------------------------------------------------------------------------------------------------------------------- |
@@ -24,8 +26,8 @@ All programs are deployed using
 | Devnet  | Lockup        | [4EauRKrNErKfsR4XetEZJNmvACGHbHnHV4R5dvJuqupC](https://solscan.io/account/4EauRKrNErKfsR4XetEZJNmvACGHbHnHV4R5dvJuqupC?cluster=devnet) |
 | Devnet  | MerkleInstant | [7XrxoQejBoGouW4V3aozTSwub7xSDjYqB4Go7YLjF9rV](https://solscan.io/account/7XrxoQejBoGouW4V3aozTSwub7xSDjYqB4Go7YLjF9rV?cluster=devnet) |
 
-The programs are verified using [Solana Verify CLI](https://github.com/Ellipsis-Labs/solana-verifiable-build/) and the
-verification status can be found on the Osec API:
+The programs have been verified using [Solana Verify CLI](https://github.com/Ellipsis-Labs/solana-verifiable-build/).
+Their verification status can be found on Osec:
 
 - [Lockup](https://verify.osec.io/status/4EauRKrNErKfsR4XetEZJNmvACGHbHnHV4R5dvJuqupC)
 - [MerkleInstant](https://verify.osec.io/status/7XrxoQejBoGouW4V3aozTSwub7xSDjYqB4Go7YLjF9rV)

docs/solana/03-fee.md

@@ -6,11 +6,13 @@ title: "Fees"
 
 ### Interface Fees
 
-The Sablier Interface charges a flat fee for certain operations. This fee is paid in the native gas token, i.e. in SOL.
+The Sablier Interface charges a flat USD fee for certain operations. This fee is paid in the native gas token of the
+network (i.e. SOL).
 
 :::info
 
-Fees are calculated based on market prices. For example, when SOL is \$200, a \$1 fee equals 0.005 SOL.
+Fees are calculated based on the SOL price at the moment of the tx. For example, if SOL is \$200, a \$1 fee equals 0.005
+SOL.
 
 :::
 
@@ -19,18 +21,34 @@ Fees are calculated based on market prices. For example, when SOL is \$200, a \$
 | Withdraw from a stream | **$1** |
 | Claim an airdrop       | **$2** |
 
-These are Interface Fees, not program-level fees. The Solana programs themselves don't charge these fees.
+These are Interface (and not program-level) fees. The SolSab programs themselves don't charge any fees.
+
+### Metaplex Fees
+
+Each of our Lockup streams has an NFT representation, in the form of a
+[Metaplex Token Metadata](https://developers.metaplex.com/token-metadata) NFT. Metaplex
+[charges](https://developers.metaplex.com/protocol-fees) a fixed fee, in SOL, for a number of operations with its
+protocol. Because of the latter, creating a Lockup stream also involves a **0.01 SOL** fee that goes directly to
+Metaplex.
 
 ### Transaction Fees
 
-Each operation on the blockchain also has a gas fee, which is independent of the Sablier fee, this is for network and
-rent of the accounts created. For more information, refer to [Solana docs](https://solana.com/docs/core/fees).
+When transacting on the Solana blockchain, you're also required to pay one or more of the following
+[transaction fees](https://solana.com/learn/understanding-solana-transaction-fees#solanas-fee-structure) (depending on
+what exactly your tx does):
+
+- Base Fee
+- Priority Fee
+- Storage Rent
+
+These fees are independent of the Sablier fees - and are used by the Solana network, e.g., to compensate the validators
+for processing your tx.
 
-These fees are an approximation, as each transaction might have a different cost.
+Here are the estimated transaction fees for some of our program instructions:
 
-| Operation                  | Fee         |
-| -------------------------- | ----------- |
-| Create a stream            | **~$5**     |
-| Withdraw from a stream     | **~$0.004** |
-| Create an airdrop campaign | **~$0.1**   |
-| Claim an airdrop           | **~$0.2**   |
+| Operation                  | Fee              |
+| -------------------------- | ---------------- |
+| Create a stream            | **~0.0137 SOL**  |
+| Withdraw from a stream     | **~0.00009 SOL** |
+| Create an airdrop campaign | **~0.0045 SOL**  |
+| Claim an airdrop           | **~0.00003 SOL** |

docs/solana/07-governance.md

@@ -4,8 +4,14 @@ sidebar_position: 7
 title: "Governance"
 ---
 
-The Protocol Admin is an account with exclusive access to collecting the fee from the treasury account, and also has the
-"upgrade authority". More concretely, the Admin is a multisig wallet and currently in control of Sablier Labs.
+SolSab program governance comprises two key functions:
+
+- Collecting accumulated protocol fees from the Treasury account
+- Upgrading the protocol (as the "upgrade authority")
+
+Both functions are exclusively controlled by the Protocol Admin account, a multisig wallet managed by Sablier Labs.
+
+The following table lists the Treasury and Protocol Admin account addresses:
 
 | Chain   | Protocol      | Role     | Address                                                                                                                                |
 | :------ | :------------ | :------- | :------------------------------------------------------------------------------------------------------------------------------------- |

…olana/accounts-architecture/01-lockup.md …a/architecture-and-diagrams/01-lockup.mddocs/solana/accounts-architecture/01-lockup.md renamed to docs/solana/architecture-and-diagrams/01-lockup.md docs/solana/accounts-architecture/01-lockup.md renamed to docs/solana/architecture-and-diagrams/01-lockup.md

@@ -4,12 +4,10 @@ sidebar_position: 1
 title: "Lockup"
 ---
 
-This section focuses on the architecture of accounts created or used in the most important instructions of the Lockup
-program.
+This section covers the program architecture, as well as the account structure and the token flow for the most important
+instructions of the Lockup program.
 
-## Account architecture
-
-### Sablier Lockup program
+## Program Architecture
 
 The `sablier_lockup` program implements these main functionalities:
 
@@ -19,7 +17,9 @@ The `sablier_lockup` program implements these main functionalities:
 - `withdraw`
 - `renounce`
 
-We will go into the details and specifics of each one later. For now, we will focus only on the accounts being created.
+The `create_stream` functionality is represented by the `create_with_timestamps_ll` and `create_with_durations_ll`
+instructions. The difference between the two is the kind of inputs required from the stream creator. However, both of
+them create the same accounts and store the same data on-chain.
 
 ```mermaid
 flowchart TD
@@ -32,8 +32,9 @@ flowchart TD
     C --> H[create_with_durations_ll]
 ```
 
-The difference between the create stream implementations is that one uses timestamps, while the other uses duration
-inputs. Though, both create the same accounts and save the same data on chain.
+## Ix Account Architecture
+
+The following sections detail the accounts created by each instruction.
 
 ### `initialize` Instruction
 
@@ -53,7 +54,7 @@ flowchart TD
 - **NFT collection mint PDA**: serves as the master mint authority for all stream NFTs
 - **NFT collection metadata PDA**: created via Metaplex CPI
 - **NFT collection master edition PDA**: created via Metaplex CPI
-- **NFT collection ATA**: associated token account owned by treasury to hold the collection NFT token
+- **NFT collection ATA**: the treasury-owned associated token account holding the collection NFT
 
 The
 [Treasury PDA](https://github.com/sablier-labs/solsab/blob/e1085fe87ea3d02556156ee446e820d150af483e/programs/lockup/src/state/treasury.rs#L5-L10)
@@ -131,10 +132,17 @@ flowchart TD
   A --> A3([start])
 ```
 
-## The Flow of the Deposit Token
+## Deposit Token Flow
+
+At stream creation, the deposit token is transferred from the sender to the stream's token account. Then, as it's being
+streamed, it can be withdrawn by the recipient. If the stream is canceled, the unstreamed token amount is refunded to
+the sender. The following diagrams illustrate how tokens move between accounts when each instruction is executed.
 
 ### `create_with_timestamps_ll` Instruction
 
+At stream creation, the deposit tokens are transferred from the sender's ATA to the stream data's ATA, where they are
+stored until withdrawn or refunded.
+
 ```mermaid
 sequenceDiagram
     actor Sender
@@ -149,7 +157,8 @@ sequenceDiagram
 
 ### `cancel` Instruction
 
-Only the sender can cancel a stream.
+Only the sender can cancel a stream. When canceled, any remaining/unstreamed tokens are refunded from the stream data's
+ATA to the sender's ATA.
 
 ```mermaid
 sequenceDiagram
@@ -165,6 +174,10 @@ sequenceDiagram
 
 ### `withdraw` Instruction
 
+The recipient can withdraw their available/streamed tokens at any time. The tokens are transferred from the stream
+data's ATA to the specified withdrawal recipient's ATA (which may be the recipient themselves or another account,
+depending on the authority of the tx signer).
+
 ```mermaid
 sequenceDiagram
     actor Recipient

…counts-architecture/02-merkle-instant.md …ecture-and-diagrams/02-merkle-instant.mddocs/solana/accounts-architecture/02-merkle-instant.md renamed to docs/solana/architecture-and-diagrams/02-merkle-instant.md docs/solana/accounts-architecture/02-merkle-instant.md renamed to docs/solana/architecture-and-diagrams/02-merkle-instant.md

@@ -4,12 +4,10 @@ sidebar_position: 2
 title: "Merkle Instant"
 ---
 
-This section focuses on the architecture of accounts created or used in the most important instructions of the Merkle
-Instant program.
+This section covers the program architecture, as well as the account structure and the token flow for the most important
+instructions of the Merkle Instant program.
 
-## Account architecture
-
-### Sablier Merkle Instant program
+## Program Architecture
 
 The `sablier_merkle_instant` program implements the following main functionalities:
 
@@ -18,8 +16,6 @@ The `sablier_merkle_instant` program implements the following main functionaliti
 - `claim`
 - `clawback`
 
-We will go into the details and specifics of each one later. For now, we will focus only on the accounts being created.
-
 ```mermaid
 flowchart TD
     A[Sablier Merkle Instant Program] --> B[initialize]
@@ -28,6 +24,10 @@ flowchart TD
     A --> E[clawback]
 ```
 
+## Ix Account Architecture
+
+The following sections detail the accounts created by each instruction.
+
 ### `initialize` Instruction
 
 ```mermaid
@@ -90,15 +90,23 @@ The
 [Claim receipt](https://github.com/sablier-labs/solsab/blob/e1085fe87ea3d02556156ee446e820d150af483e/programs/merkle_instant/src/state/claim_receipt.rs#L6)
 account serves as proof of claim for the given recipient.
 
-## The Flow of the Airdrop Token
+## Airdrop Token Flow
+
+The airdrop token flow begins when the campaign creator funds the campaign's ATA. Once funded and the campaign has
+started, eligible recipients can claim their tokens. The campaign creator can clawback any remaining tokens after the
+campaign expires. The following diagrams illustrate how tokens move between accounts when each instruction is executed.
 
 ### `create_campaign` Instruction
 
-This instruction does not perform the airdrop token transfer, but the transfer is expected to be made as a separate
-transaction. Therefore, the campaign ATA is assumed to be funded after the campaign creation.
+This instruction creates the campaign account and its ATA, but does not perform the airdrop token transfer. The campaign
+creator must fund the campaign ATA in a separate transaction after campaign creation. After that, the campaign ATA will
+hold all tokens available for distribution to eligible recipients.
 
 ### `claim` Instruction
 
+Eligible recipients can claim their airdrop tokens by providing a valid Merkle proof. When claimed, tokens are
+transferred from the campaign ATA to the recipient's ATA.
+
 ```mermaid
 sequenceDiagram
     actor Claimer
@@ -113,6 +121,9 @@ sequenceDiagram
 
 ### `clawback` Instruction
 
+After the campaign expiration time, the campaign creator can clawback any remaining/unclaimed tokens. These tokens are
+transferred from the campaign ATA back to the campaign creator's ATA.
+
 ```mermaid
 sequenceDiagram
     actor CampaignCreator

…na/accounts-architecture/_category_.json …rchitecture-and-diagrams/_category_.jsondocs/solana/accounts-architecture/_category_.json renamed to docs/solana/architecture-and-diagrams/_category_.json docs/solana/accounts-architecture/_category_.json renamed to docs/solana/architecture-and-diagrams/_category_.json

@@ -1,5 +1,5 @@
 {
   "collapsed": false,
-  "label": "Accounts Architecture",
+  "label": "Architecture & Diagrams",
   "position": 4
 }