Merge pull request #184 from 0xMiden/brian/psm-docs

Add PSM and Private Multisig documentation under Solutions

Author: BrianSeong99

docs/builder/develop/_category_.json

@@ -1,4 +1,4 @@
 {
   "label": "Develop on Miden",
-  "position": 4
+  "position": 5
 }

docs/builder/glossary.md

@@ -44,10 +44,18 @@ A Batch allows multiple transactions to be grouped together, these batches will
 
 A Block is a fundamental data structure which groups multiple batches together and forms the blockchain's state.
 
+## Canonicalization
+
+The background process by which [Miden Guardian](./solutions/miden-guardian/) promotes candidate deltas to canonical status by verifying them against the Miden network.
+
 ## Delta
 
 A Delta represents the changes between two states `s` and `s'`. Applying a Delta `d` to `s` would result in `s'`.
 
+## Delta Proposal
+
+A coordination mechanism in [Miden Guardian](./solutions/miden-guardian/) that allows multiple signers to propose, review, and co-sign state changes before they are promoted to a canonical delta.
+
 ## Felt
 
 A Felt or Field Element is a data type used for cryptographic operations. It represents an element in the finite field used in Miden.
@@ -60,6 +68,14 @@ A fundamental module of the MidenVM that acts as a base layer by providing core
 
 An assembly language specifically designed for the Miden VM. It's a low-level programming language with specialized instructions optimized for zero-knowledge proof generation.
 
+## Miden Guardian
+
+Infrastructure built by OpenZeppelin for managing private account state on Miden. Guardian provides a server and client SDKs for backing up, syncing, and coordinating state across devices and parties without trust assumptions. See the [Miden Guardian documentation](./solutions/miden-guardian/).
+
+## MultiSig
+
+A multi-signature account on Miden that requires a configurable threshold (N-of-M) of authorized signers to approve transactions before execution. MultiSig workflows are coordinated through [Miden Guardian](./solutions/miden-guardian/).
+
 ## Note
 
 A Note is a fundamental data structure that represents an offchain asset or a piece of information that can be transferred between accounts. Miden's UTXO-like (Unspent Transaction Output) model is designed around the concept of notes. There are output notes which are new notes created by the transaction and input notes which are consumed (spent) by the transaction.
@@ -84,6 +100,10 @@ A nullifier is a cryptographic commitment that marks a note as spent, preventing
 
 A Prover is responsible for generating zero-knowledge proofs that attest to the correctness of the execution of a program without revealing the underlying data.
 
+## Threshold Signature
+
+A cryptographic scheme where a minimum number of signers (the threshold) out of a total group must sign for a transaction to be valid. Used in Miden's MultiSig accounts.
+
 ## Word
 
 A Word is a data structure that represents the basic unit of computation and storage in Miden, it is composed or four Felt's.

docs/builder/index.md

@@ -78,6 +78,29 @@ import DocCard from '@theme/DocCard';
   </div>
 </div>
 
+<div className="row">
+  <div className="col col--6">
+    <DocCard
+      item={{
+        type: 'link',
+        href: './solutions/miden-guardian',
+        label: 'Miden Guardian',
+        description: 'Backup, sync, and coordinate private account state with Guardian.',
+      }}
+    />
+  </div>
+  <div className="col col--6">
+    <DocCard
+      item={{
+        type: 'link',
+        href: './solutions/private-multisig',
+        label: 'Private Multisig',
+        description: 'Multi-party threshold signature workflows on Miden.',
+      }}
+    />
+  </div>
+</div>
+
 <div className="row">
   <div className="col col--6">
     <DocCard

docs/builder/migration/_category_.json

@@ -1,6 +1,6 @@
 {
   "label": "Migration",
-  "position": 6,
+  "position": 7,
   "link": {
     "type": "doc",
     "id": "builder/migration/index"

docs/builder/quick-start/accounts.md

@@ -158,7 +158,7 @@ npm run dev
 ```
 
 :::tip
-For detailed frontend setup guidance, see the [Web Client tutorial](/miden-tutorials/web-client/create_deploy_tutorial#step-2-set-up-the-webclient).
+For detailed frontend setup guidance, see the [Tutorials section](../develop/tutorials/rust-compiler/).
 :::
 
 ## Creating Accounts Programmatically

docs/builder/quick-start/your-first-smart-contract/test.md

@@ -299,7 +299,7 @@ Congratulations! You've successfully completed the Miden smart contract quick st
 
 To deepen your knowledge, we recommend exploring the following resources:
 
-- Visit the [Tutorials section](/miden-tutorials) for detailed, hands-on guides on topics such as contract interactions, advanced storage, custom note scripting, and integrating with external applications via the Miden Web Client.
-- For in-depth technical explanations of core concepts, consult the [Protocol section](/miden-base) of the documentation. Here you'll find comprehensive information on Miden's architecture, account model, transaction lifecycle, and the underlying zero-knowledge technology that powers the network.
+- Visit the [Tutorials section](../../develop/tutorials/rust-compiler/) for detailed, hands-on guides on topics such as contract interactions, advanced storage, custom note scripting, and integrating with external applications.
+- For in-depth technical explanations of core concepts, consult the [Core Concepts section](../../../core-concepts/) of the documentation. Here you'll find comprehensive information on Miden's architecture, account model, transaction lifecycle, and the underlying zero-knowledge technology that powers the network.
 
 The foundational patterns and concepts you've practiced in this Quick Start will enable you to build complex, privacy-preserving applications on the Miden network. Continue with the resources above to take your development further!

docs/builder/solutions/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Solutions",
+  "position": 4
+}

docs/builder/solutions/miden-guardian/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Miden Guardian",
+  "position": 4
+}

docs/builder/solutions/miden-guardian/core-concepts/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Core Concepts",
+  "position": 1
+}

docs/builder/solutions/miden-guardian/core-concepts/architecture.md

@@ -0,0 +1,110 @@
+---
+title: Architecture
+sidebar_position: 1
+---
+
+# Architecture
+
+Guardian sits between Miden clients and the Miden network, providing an off-chain coordination layer for private account state.
+
+## System overview
+
+```mermaid
+graph LR
+    A["Miden Client A<br/>(Desktop)"] <-->|"gRPC / HTTP"| Guardian["Guardian Server"]
+    B["Miden Client B<br/>(Mobile)"] <-->|"gRPC / HTTP"| Guardian
+    Guardian <-->|"Validates state"| Node["Miden Node"]
+```
+
+- **Miden Client** handles transaction execution, proving, and local state management.
+- **Guardian Server** stores state snapshots and deltas, authenticates requests, validates changes against the network, and coordinates multi-party workflows.
+- **Miden Node** is the network's RPC endpoint that Guardian validates state against.
+
+Each account is independently configured on Guardian with its own authentication policy and storage. Clients interact with Guardian through either gRPC or HTTP — both interfaces expose the same semantics.
+
+## End-to-end transaction flow
+
+Transactions proceed through a step-by-step process to ensure consistency and verifiability:
+
+```mermaid
+sequenceDiagram
+    participant Client as Miden Client
+    participant Guardian as Guardian Server
+    participant Chain as Miden Network
+
+    Client->>Client: 1. Execute transaction locally<br/>Generate delta
+    Client->>Guardian: 2. Submit delta for acknowledgment
+    Guardian->>Guardian: 3. Validate delta against policies
+    Guardian->>Guardian: Co-sign as "candidate"
+    Guardian-->>Client: Return ack signature
+    Client->>Chain: 4. Submit ZK proof + state update
+    Chain-->>Guardian: 5. Guardian monitors on-chain commitment
+    alt Commitment matches candidate
+        Guardian->>Guardian: Promote to "canonical"
+        Guardian-->>Client: Propagate confirmed delta
+    else Commitment mismatch
+        Guardian->>Guardian: Mark as "discarded"
+        Guardian-->>Client: Signal resync needed
+    end
+```
+
+1. **Local execution**: The user computes a transaction locally, generating a delta (state change).
+2. **Delta submission**: The user sends the delta to Guardian for acknowledgment.
+3. **Guardian acknowledgment**: Guardian validates the delta and co-signs it, designating it as a "candidate" state.
+4. **Proof submission**: The user generates the ZK proof and submits it to the chain.
+5. **Canonical confirmation**: Guardian monitors the chain. If the on-chain commitment matches the candidate, the state becomes "canonical" and is propagated to other devices or signers.
+
+## Multi-device sync
+
+For users with multiple devices, Guardian keeps state synchronized seamlessly:
+
+```mermaid
+sequenceDiagram
+    participant Desktop as Desktop
+    participant Guardian as Guardian Server
+    participant Mobile as Mobile
+
+    Desktop->>Desktop: Execute transaction
+    Desktop->>Guardian: Push delta
+    Guardian->>Guardian: Validate & acknowledge
+    Desktop->>Desktop: Submit proof to chain
+    Guardian->>Guardian: Confirm canonical
+    Mobile->>Guardian: Get state
+    Guardian-->>Mobile: Return latest state
+    Mobile->>Mobile: Replay delta locally
+    Note over Mobile: State now matches Desktop
+```
+
+The desktop executes a transaction and pushes the delta to Guardian. After on-chain confirmation, Guardian propagates the canonical delta to the mobile device, which replays it locally — all without querying the chain directly.
+
+## Account management
+
+Accounts are configured with per-account authentication based on public keys (commitments). During setup, Guardian records which keys are authorized to manage the account.
+
+For each request, the client signs a payload with one of those keys and the server verifies the signature against the account's authorized keys. See [Components](./components.md) for details on the auth model.
+
+## Canonicalization
+
+Canonicalization is the process of validating that a state transition (delta) is valid against the on-chain commitment. It is optional and mainly used in multi-user setups.
+
+```mermaid
+stateDiagram-v2
+    [*] --> candidate : push_delta
+    candidate --> canonical : On-chain commitment matches
+    candidate --> discarded : On-chain commitment mismatch
+    canonical --> [*]
+    discarded --> [*]
+```
+
+- **Candidate mode** (default): A background worker promotes or discards deltas after a configurable delay and network verification.
+- **Optimistic mode**: Deltas become canonical immediately, skipping the verification window.
+
+| Parameter | Default | Description |
+|---|---|---|
+| `delay_seconds` | 900 (15 min) | How long a candidate waits before the worker checks it. |
+| `check_interval_seconds` | 60 (1 min) | How often the worker runs. |
+
+## Common use cases
+
+- **Single-user accounts**: Back up and sync state securely. If a device is lost, recover state from Guardian.
+- **Multi-user accounts**: Coordinate state and transactions between participants. Guardian helps keep everyone on the latest canonical state.