Documentation improvement: content and UI

astro.config.mjs

@@ -6,7 +6,7 @@ import starlight from "@astrojs/starlight";
 export default defineConfig({
   integrations: [
     starlight({
-      title: "MIST.cash SDK",
+      title: "MIST Docs",
       description:
         "Privacy-focused SDK for zero-knowledge transactions on Starknet",
       social: [
@@ -18,36 +18,72 @@ export default defineConfig({
       ],
       customCss: ["./src/styles/custom.css"],
       sidebar: [
+        { label: "Welcome", slug: "index" },
         {
-          label: "Start Here",
+          label: "Introduction",
+          collapsed: false,
           items: [
-            { label: "Introduction", slug: "" },
-            { label: "Getting Started", slug: "getting-started" },
+            { label: "Overview", slug: "introduction/overview" },
+            { label: "Community", slug: "introduction/mission" },
+            { label: "FAQ", slug: "introduction/faq" },
           ],
         },
         {
-          label: "Packages",
+          label: "Features",
+          collapsed: false,
           items: [
-            { label: "@mistcash/sdk", slug: "packages/core" },
-            { label: "@mistcash/config", slug: "packages/config" },
-            { label: "@mistcash/react", slug: "packages/react" },
+            { label: "Private Payment", slug: "features/private-payment" },
+            {
+              label: "Partial Withdrawals",
+              slug: "features/partial-withdrawals",
+            },
+            { label: "Off-Ramping", slug: "features/off-ramping" },
+            { label: "Compliance", slug: "features/compliance" },
+          ],
+        },
+        {
+          label: "How It Works",
+          collapsed: false,
+          items: [
+            { label: "Concepts", slug: "how-it-works/concepts-glossary" },
+            { label: "Architecture", slug: "how-it-works/architecture" },
+            {
+              label: "Transaction Flow",
+              slug: "how-it-works/tx-lifecycle",
+            },
+            { label: "Cryptography", slug: "how-it-works/cryptography" },
           ],
         },
         {
           label: "Guides",
+          collapsed: false,
           items: [
-            { label: "Depositing Tokens", slug: "guides/deposit" },
-            { label: "Withdrawing Tokens", slug: "guides/withdraw" },
-            { label: "Zero-Knowledge Proofs", slug: "guides/zero-knowledge" },
+            { label: "Quickstart", slug: "guides/quickstart" },
+            { label: "Deposit", slug: "guides/deposit" },
+            { label: "Withdraw", slug: "guides/withdraw" },
             { label: "Merkle Trees", slug: "guides/merkle-trees" },
+            {
+              label: "Zero-Knowledge Proofs",
+              slug: "guides/zero-knowledge",
+            },
           ],
         },
         {
           label: "Reference",
+          collapsed: false,
           items: [
-            { label: "API Reference", slug: "reference/api" },
-            { label: "Types", slug: "reference/types" },
+            { label: "SDK", slug: "reference/sdk" },
             { label: "Contract ABI", slug: "reference/contract" },
+            { label: "Types", slug: "reference/types" },
+          ],
+        },
+        {
+          label: "Packages",
+          collapsed: false,
+          items: [
+            { label: "@mistcash/sdk", slug: "packages/core" },
+            { label: "@mistcash/config", slug: "packages/config" },
+            { label: "@mistcash/react", slug: "packages/react" },
           ],
         },
       ],

src/content/docs/features/compliance.md

@@ -0,0 +1,22 @@
+---
+title: Compliance
+description: How MIST.cash balances privacy with regulatory compliance.
+---
+
+MIST.cash is designed with compliance in mind. Privacy and regulatory adherence are not mutually exclusive.
+
+## Voluntary Disclosure
+
+Users can optionally generate a **viewing key** that allows a designated third party (e.g., an auditor or regulator) to verify their transaction history without exposing it publicly.
+
+## Selective De-shielding
+
+Users retain the ability to prove the origin of their funds when needed, such as for tax reporting or regulatory inquiries, by revealing specific deposit-withdrawal links.
+
+## Blocked Addresses
+
+MIST.cash integrates with on-chain sanctions lists to prevent sanctioned addresses from interacting with the protocol.
+
+## Philosophy
+
+We believe privacy is a fundamental right, but we also recognize the importance of working within legal frameworks. MIST.cash provides tools that empower users to be both private and compliant.

src/content/docs/features/off-ramping.md

@@ -0,0 +1,22 @@
+---
+title: Off-Ramping
+description: Convert shielded tokens back to fiat or other chains.
+---
+
+MIST.cash provides pathways to off-ramp shielded tokens, allowing users to convert their private balances back into fiat currency or bridge to other chains.
+
+## Supported Off-Ramps
+
+- **Fiat gateways** -- Integrate with supported fiat on/off-ramp providers.
+- **Cross-chain bridges** -- Bridge shielded tokens to other L1/L2 networks.
+- **DEX swaps** -- Swap withdrawn tokens directly on Starknet DEXes.
+
+## How It Works
+
+1. Withdraw tokens from the shielded pool to a fresh address.
+2. Use the withdrawn tokens with any supported off-ramp provider or DEX.
+3. The off-ramp provider processes the conversion without knowledge of the original deposit.
+
+## Privacy Considerations
+
+For maximum privacy, use a fresh address for each withdrawal and avoid reusing addresses across multiple off-ramp transactions.

src/content/docs/features/partial-withdrawals.md

@@ -0,0 +1,20 @@
+---
+title: Partial Withdrawals
+description: Withdraw only a portion of your shielded balance.
+---
+
+MIST.cash supports partial withdrawals, allowing users to withdraw a fraction of their deposited amount while keeping the remainder in the shielded pool.
+
+## How It Works
+
+When you make a partial withdrawal, the protocol splits your original commitment into two new commitments -- one representing the withdrawn amount and one representing the remaining balance. Both operations are protected by zero-knowledge proofs.
+
+## Benefits
+
+- **Flexibility** -- No need to withdraw the full amount at once.
+- **Improved privacy** -- Partial withdrawals make it harder for observers to correlate deposits and withdrawals by amount.
+- **Cost efficiency** -- Withdraw only what you need, when you need it.
+
+## Example
+
+If you deposited 1 ETH, you could withdraw 0.3 ETH and retain a shielded note for the remaining 0.7 ETH. The 0.7 ETH note can be used for future withdrawals.

src/content/docs/features/private-payment.md

@@ -0,0 +1,25 @@
+---
+title: Private Payment
+description: How MIST.cash enables private payments on Starknet.
+---
+
+Private payments are the core feature of MIST.cash. By leveraging zero-knowledge proofs, users can transfer value without revealing the sender, receiver, or amount on-chain.
+
+## How It Works
+
+1. The sender deposits tokens into the MIST.cash shielded pool.
+2. The sender shares a **note** (a secret) with the recipient off-chain.
+3. The recipient uses the note to generate a ZK proof and withdraw the tokens to their address.
+
+## Privacy Guarantees
+
+- **Sender anonymity** -- The withdrawal cannot be linked back to the deposit.
+- **Receiver anonymity** -- The recipient address has no on-chain connection to the sender.
+- **Amount privacy** -- When using fixed denominations, the amount is indistinguishable from other deposits in the same pool.
+
+## Use Cases
+
+- Payroll and salary payments
+- Donations without public disclosure
+- Private peer-to-peer transfers
+- Protecting trading strategies

src/content/docs/getting-started.mdx → src/content/docs/guides/quickstart.mdx

@@ -1,5 +1,5 @@
 ---
-title: Getting Started
+title: Quickstart
 description: Install the MIST.cash SDK and run your first privacy transaction.
 ---
 
@@ -149,6 +149,56 @@ The SDK supports the following tokens on Starknet mainnet:
 
 See [`tokensData`](/packages/config#supported-tokens) in `@mistcash/config` for full addresses and metadata.
 
+## Examples
+
+### Deposit and Withdraw
+
+```typescript
+import { MistClient } from "@mistcash/sdk";
+
+const client = new MistClient({ provider, network: "mainnet" });
+
+// Deposit 0.1 ETH
+const { note } = await client.createDeposit({ token: "ETH", amount: "0.1" });
+await client.deposit(note.commitment);
+
+// Later: withdraw to a new address
+await client.withdraw({ note: note.secret, recipient: recipientAddress });
+```
+
+### Partial Withdrawal
+
+```typescript
+// Withdraw only 0.03 ETH, keep 0.07 ETH shielded
+const { remainingNote } = await client.partialWithdraw({
+  note: originalNote,
+  amount: "0.03",
+  recipient: recipientAddress,
+});
+
+// remainingNote can be used for future withdrawals
+```
+
+### Using a Relayer
+
+```typescript
+const client = new MistClient({
+  provider,
+  network: "mainnet",
+  relayerUrl: "https://relayer.mistcash.example",
+});
+
+// Withdrawals will be submitted via the relayer
+await client.withdraw({ note, recipient: freshAddress });
+```
+
+### Checking Deposit Status
+
+```typescript
+const status = await client.getDepositStatus(commitment);
+console.log(status); // { deposited: true, withdrawn: false, timestamp: 1700000000 }
+```
+
 ## Next Steps
 
 - Learn about the [Core SDK](/packages/core) for low-level cryptographic operations

src/content/docs/how-it-works/architecture.md

@@ -0,0 +1,36 @@
+---
+title: Architecture
+description: System architecture of the MIST.cash protocol.
+---
+
+MIST.cash consists of several components that work together to provide private transactions.
+
+## Smart Contracts
+
+The core contract manages deposits, the Merkle tree, nullifier tracking, and withdrawal verification. It is deployed on Starknet and written in Cairo.
+
+## Client SDK
+
+The TypeScript SDK handles proof generation, note management, and contract interaction. It runs entirely client-side to ensure secrets never leave the user's device.
+
+## Relayer (Optional)
+
+A relayer is an off-chain service that submits withdrawal transactions on behalf of users. This is useful for withdrawing to addresses with no gas, preserving privacy by avoiding a direct on-chain link.
+
+## System Diagram
+
+```
+User --> SDK --> [Generate Proof] --> Relayer (optional) --> Starknet Contract
+                                                                  |
+                                                           Verify Proof
+                                                                  |
+                                                          Transfer Tokens
+```
+
+## Data Flow
+
+1. User creates a note (secret + nullifier) via the SDK.
+2. SDK computes the commitment and submits the deposit transaction.
+3. For withdrawal, the SDK generates a ZK proof locally.
+4. The proof is submitted (directly or via relayer) to the contract.
+5. The contract verifies and processes the withdrawal.

src/content/docs/how-it-works/concepts-glossary.md

@@ -0,0 +1,32 @@
+---
+title: Concepts
+description: Key concepts and terminology used in MIST.cash.
+---
+
+## Core Concepts
+
+### Commitment
+
+A cryptographic hash that represents a deposit. It is stored on-chain without revealing the deposit details.
+
+### Nullifier
+
+A unique value derived from the deposit secret. When a withdrawal is made, the nullifier is published to prevent double-spending.
+
+### Merkle Tree
+
+A data structure that stores all deposit commitments. The ZK proof demonstrates membership in this tree without revealing which leaf (deposit) belongs to the prover.
+
+### Note
+
+A secret value shared between sender and recipient that encodes the information needed to withdraw funds.
+
+## Glossary
+
+| Term | Definition |
+|------|-----------|
+| **Shielded pool** | The smart contract holding all deposited tokens |
+| **ZK proof** | A zero-knowledge proof that validates a withdrawal |
+| **Relayer** | An optional third-party service that submits withdrawal transactions on behalf of users |
+| **Denomination** | A fixed deposit amount for a given pool |
+| **Anonymity set** | The set of all deposits in a pool that a withdrawal could plausibly originate from |

src/content/docs/how-it-works/cryptography.md

@@ -0,0 +1,32 @@
+---
+title: Cryptography
+description: Cryptographic primitives used in MIST.cash.
+---
+
+MIST.cash relies on several cryptographic primitives to ensure privacy and security.
+
+## Hash Functions
+
+The protocol uses **Pedersen hashing** for commitments and Merkle tree construction. Pedersen hashes are efficient to compute inside STARK circuits, making them ideal for Starknet.
+
+## Zero-Knowledge Proofs
+
+MIST.cash leverages Starknet's native STARK proving system. This provides:
+
+- **No trusted setup** -- Unlike SNARKs, STARKs do not require a ceremony.
+- **Post-quantum security** -- STARKs are resistant to quantum computing attacks.
+- **Scalability** -- Proof verification is efficient on-chain.
+
+## Commitment Scheme
+
+A deposit commitment is computed as:
+
+```
+commitment = hash(secret, nullifier)
+```
+
+The `secret` and `nullifier` are randomly generated by the user. The commitment is public; the preimage values remain private.
+
+## Nullifier Derivation
+
+The nullifier is derived deterministically from the secret to ensure each deposit can only be withdrawn once. Publishing the nullifier on withdrawal prevents double-spending without revealing the deposit.

src/content/docs/how-it-works/tx-lifecycle.md

@@ -0,0 +1,30 @@
+---
+title: Transaction Flow
+description: Step-by-step walkthrough of a MIST.cash transaction.
+---
+
+A MIST.cash transaction goes through several stages from deposit to withdrawal.
+
+## 1. Deposit
+
+The user generates a random secret and computes a commitment (hash of the secret). They then call the `deposit()` function on the MIST.cash contract, sending tokens along with the commitment.
+
+## 2. Commitment Insertion
+
+The contract inserts the commitment into an on-chain Merkle tree. This tree stores all deposit commitments.
+
+## 3. Proof Generation
+
+When the user (or recipient) wants to withdraw, they generate a zero-knowledge proof that demonstrates:
+
+- They know a secret corresponding to a commitment in the Merkle tree.
+- They have computed a valid nullifier for that commitment.
+- The nullifier has not been used before.
+
+## 4. Withdrawal
+
+The user submits the ZK proof along with the nullifier and the recipient address. The contract verifies the proof, marks the nullifier as spent, and transfers the tokens to the recipient.
+
+## 5. Confirmation
+
+The transaction is confirmed on Starknet. The recipient now has the tokens in their wallet with no on-chain link to the original depositor.

src/content/docs/index.mdx

@@ -1,5 +1,5 @@
 ---
-title: Introduction
+title: Welcome
 description: Privacy-focused SDK for zero-knowledge transactions on Starknet.
 ---