Merge pull request #141 from oasisprotocol/uniyalabhishek/feature/privana-docs-migration

feat: add Privana Docusaurus docs site

Author: uniyalabhishek

.github/workflows/ci-docs.yml

@@ -0,0 +1,44 @@
+# NOTE: This name appears in GitHub's Checks API and in workflow's status badge.
+name: ci-docs
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  ci-docs:
+    # NOTE: This name appears in GitHub's Checks API.
+    name: ci-docs
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: docs
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20.x
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Build website
+        run: bun run build
+
+      - name: Deploy to GitHub Pages
+        if: github.event_name == 'push' && github.ref == 'refs/heads/master'
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/build
+          force_orphan: true
+          cname: docs.privana.finance
+          user_name: github-actions[bot]
+          user_email: 41898282+github-actions[bot]@users.noreply.github.com

docs/.gitignore

@@ -0,0 +1,22 @@
+# Docusaurus build artefacts
+/.docusaurus
+/build
+/node_modules
+
+# Caches
+/.cache-loader
+
+# Local env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# Logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# TypeScript
+*.tsbuildinfo

docs/README.md

@@ -0,0 +1,23 @@
+# Privana documentation
+
+Source for [docs.privana.finance](https://docs.privana.finance). Built with [Docusaurus 3](https://docusaurus.io/).
+
+The Markdown content lives under [`docs/`](./docs/). The Docusaurus app shell (config, theme, sidebar) lives in this directory.
+
+## Local development
+
+Requires [Bun](https://bun.sh/) and Node ≥ 20.
+
+```bash
+bun install        # install deps from bun.lock
+bun start          # dev server with hot reload at http://localhost:3000
+```
+
+Other useful scripts:
+
+```bash
+bun run build      # production build → ./build/
+bun run serve      # serve the production build locally
+bun run typecheck  # run tsc against docusaurus.config.ts and sidebars.ts
+bun run clear      # clear Docusaurus cache when something is misbehaving
+```

docs/bun.lock

@@ -0,0 +1,37 @@
+---
+id: deep-dive
+title: "Architecture Deep Dive"
+sidebar_position: 2
+description: "The full Privana architecture, from the layers that make it up to the components that handle your trades and policies."
+---
+
+The full Privana architecture, from the layers that make it up to the components that handle your trades and policies.
+
+The Privana architecture has four principal layers: integrators (the Privana app and third-party applications), the SDK interface, the liquidity infrastructure, and the core service. Here's how they fit together.
+
+```mermaid
+flowchart TB
+    A["<b>Integrators</b> — Privana app + third-party applications<br/>Any Web3 product can build on Privana via the SDK"]
+    B["<b>Privana SDK</b> — REST & WebSocket API (runs inside ROFL)<br/>Key encumbrance · session access · private trading · yield · automation"]
+    C["<b>Core Service</b> (inside Oasis Sapphire TEE)<br/><b>Accounting Block:</b> confidential balance tracking, deposit monitoring, KYT, finality reconciliation<br/><b>Microservices Block:</b> trading microservice, yield microservice (modular — more services planned)"]
+    D["<b>Liquidity Infrastructure</b> — TEE-managed pooled vaults on Ethereum, Base, and HyperEVM<br/>Seeded with inventory · all user deposits flow here · privacy through pooling"]
+    A --> B
+    B --> C
+    C --> D
+```
+
+### The accounting block
+
+The accounting block is a set of Oasis Sapphire confidential smart contracts that function as the system's internal state. It maintains a confidential mapping of deposit addresses to asset balances and handles deposit monitoring, balance registration, transaction screening (KYT), balance validation before trades, routing of validated intents to the correct microservice, finality reconciliation after trade execution, and withdrawal processing across all supported chains.
+
+### The microservices block
+
+The microservices block implements the execution logic for DeFi operations. For the MVP, two microservices are provided: trading and yield (covered in the [Private Swaps](../features/private-swaps.md) and [Idle Yield](../features/idle-yield.md) sections). The modular architecture is designed for horizontal expansion — additional microservices like perpetuals trading or lending can be added without modifying the core accounting logic, and each new service automatically inherits the same key-encumbrance and privacy guarantees.
+
+### Remote attestation
+
+Attestation reports, signed by Intel's hardware root of trust, allow you to verify remotely that the enclave is running exactly the code it claims to be running. This means you don't need to trust Privana's word about what code is executing — you can cryptographically verify it. This is a stronger guarantee than an audit alone can provide.
+
+### What Privana enables beyond DeFi
+
+Because Privana exposes a composable SDK, it's not limited to DeFi applications. Any Web3 product that needs privacy, session-based access, or automated policy execution can integrate it. The Oasis team is also developing a gaming application that uses Privana to let players transact with real assets without signing each action — time-bounded access-control policies create a seamless experience comparable to Web2 gaming.

docs/docs/architecture/deep-dive.md

@@ -0,0 +1,34 @@
+---
+id: fallback-recovery
+title: "Fallback & Recovery"
+sidebar_position: 3
+description: "What happens if the enclave goes offline permanently, or if Privana ceases to exist? The answer is built into the system — not a service promise."
+---
+
+What happens if the enclave goes offline permanently, or if Privana ceases to exist? The answer is built into the system — not a service promise.
+
+Privana uses a fallback system informed by the sentinel-wallet design described in the Liquefaction research paper:
+
+```js
+// The Ethereum-based liveness monitor
+Ethereum contract monitors Oasis Sapphire liveness
+  → Checks for valid response from enclave every ~24 hours
+  → If NO response for 7 days:
+      → Challenge period opens (publicly visible on-chain)
+      → Backup TEE committee reconstructs vault keys
+          from Shamir secret shares (distributed — no single party alone)
+      → Keys are released to the ACCESS MANAGER
+          (this is you — the vault owner)
+      → You can then sweep your assets directly
+
+// No trust in Privana required for recovery
+// Recovery process is deterministic and on-chain
+```
+
+The fallback is a **smart contract on Ethereum**, not a process Privana controls. It triggers automatically if the enclave becomes unresponsive for a week. A distributed reconstruction process — using Shamir secret shares held by multiple independent parties — allows the vault keys to be recovered by you, without Privana's involvement.
+
+:::tip[The important point]
+
+Your assets are never permanently locked. Even if Privana ceases operations, your funds are recoverable within a week via the on-chain fallback mechanism. This is a **system guarantee**, not a service-level agreement.
+
+:::

docs/docs/architecture/fallback-recovery.md

@@ -0,0 +1,38 @@
+---
+id: oasis-sapphire
+title: "Oasis Sapphire"
+sidebar_position: 1
+description: "Oasis Sapphire is the confidential blockchain Privana runs on — an EVM platform whose smart contracts execute inside Intel SGX enclaves."
+---
+
+Oasis Sapphire is the confidential blockchain that everything in Privana runs on. It provides the hardware-secured foundation that makes private, non-custodial DeFi possible.
+
+**[Oasis Sapphire](https://docs.oasis.io/dapp/sapphire/)** is a smart contract platform built on the [Oasis Network](https://oasis.net/) that runs the Ethereum Virtual Machine (EVM) entirely within Intel SGX enclaves. This means smart contract logic *and* its state are confidential by default — transactions are encrypted, contract storage is encrypted, and even the validators running the network cannot read what's happening inside a contract.
+
+Sapphire provides several properties that are critical to Privana:
+
+### Confidential State
+
+Contract storage is encrypted on-chain and in memory. State is accessible only to the executing TEE. This is what keeps your balances, policies, and trade history private. [Learn more →](https://docs.oasis.io/dapp/sapphire/)
+
+### Rollback Protection
+
+Keys inside the enclave cannot be "rewound" to a previous state — preventing attacks where someone rolls back enclave state to re-use a spent nonce. Sapphire handles this at the platform level.
+
+### Off-Chain Simulation
+
+Sapphire functions can be invoked via free, off-chain queries that simulate transactions without modifying storage. Both on-chain and off-chain invocations run inside the TEE and require signed authentication — enabling cost-efficient policy evaluation.
+
+### EVM Compatibility
+
+Sapphire supports standard Solidity smart contracts. Developers don't need specialized TEE knowledge to build on it — the confidentiality layer is handled by the platform.
+
+### ROFL: Runtime Off-chain Logic
+
+Privana also uses **[ROFL](https://docs.oasis.io/build/rofl/)** (Runtime Off-chain Logic) — containers running inside a TEE that are attested on-chain by Oasis Sapphire. The Privana SDK exposes its REST and WebSocket API through ROFL, meaning the entire communication channel between the Privana app and the Privana service runs inside attested, TEE-secured containers. Sapphire can seamlessly verify that EVM transactions originate from a specific ROFL instance.
+
+### Cross-chain signing
+
+Here's what makes this architecture powerful for users: an Oasis Sapphire contract running inside a TEE can **sign valid transactions for any external chain**. Your Ethereum swap is signed inside an Oasis Sapphire enclave and submitted directly to Ethereum — never passing through a public Ethereum mempool. The target chain receives a completed, signed transaction. There is no window in which bots can see your intent.
+
+For more technical detail, see the [Oasis Sapphire developer documentation](https://docs.oasis.io/dapp/sapphire/) and the [Oasis Protocol overview](https://oasis.net/).

docs/docs/architecture/oasis-sapphire.md

@@ -0,0 +1,40 @@
+---
+id: research-basis
+title: "Research Basis"
+sidebar_position: 5
+description: "Privana's architecture is grounded in peer-reviewed cryptographic research published by Cornell Tech."
+---
+
+Privana's architecture is grounded in peer-reviewed cryptographic research published by Cornell Tech.
+
+### Primary Research Paper
+
+**"Liquefaction: Privately Liquefying Blockchain Assets"**  
+Austgen, Fábrega, Kelkar, Vilardell, Allen, Babel, Yu, and Juels — Cornell Tech  
+arXiv: [2412.02634](https://arxiv.org/abs/2412.02634), December 2024
+
+This paper introduces key encumbrance as a primitive, formalizes the SEAO assumption that conventional wallets rely on, and proves security properties of TEE-based policy governance. The paper demonstrates that TEE-based key encumbrance can break the Single-Entity Address-Ownership assumption, enabling private renting, sharing, and pooling of blockchain assets and privileges. Privana is the Oasis Network's production implementation of the Liquefaction framework.
+
+### Key concepts from the research
+
+#### Key Encumbrance
+
+The core primitive. A private key generated and held within a TEE, governed by programmable access-control policies. Enables automation without custody transfer.
+
+#### SEAO Assumption
+
+Single-Entity Address-Ownership — the assumption that one blockchain address is controlled by a single entity. Key encumbrance breaks this in a controlled, beneficial way.
+
+#### Asset-Time Segmentation
+
+The principle that a given asset is exclusively controlled by one sub-policy at any given time. Prevents deadlock and double-spend between competing policies.
+
+#### Overlay Smart Contracts
+
+Because encumbered keys are managed off-chain (in TEEs), smart-contract-like logic can be applied to chains that have no native smart contract support — Bitcoin, Dogecoin, Litecoin, etc.
+
+### Additional references
+
+The FlexVaults whitepaper cites several additional works relevant to the security model: Kelkar et al. on Complete Knowledge proofs (ACM CCS, 2024), Jean-Louis et al. on privacy flaws in TEE-based platforms (ePrint 2023/378), and Van Schaik et al. on SGX security (IEEE S&P, 2024). For readers interested in the full security analysis, the [Liquefaction paper](https://arxiv.org/abs/2412.02634) is the recommended starting point.
+
+For Oasis-specific technical resources: [Sapphire developer documentation](https://docs.oasis.io/dapp/sapphire/), [ROFL documentation](https://docs.oasis.io/build/rofl/), and the [Oasis Protocol overview](https://oasis.net/).

docs/docs/architecture/research-basis.md

@@ -0,0 +1,24 @@
+---
+id: trust-model
+title: "Trust Model"
+sidebar_position: 4
+description: "No system is trustless. Privana minimizes trust requirements — but you should understand exactly what assumptions remain."
+---
+
+No system is trustless. Privana minimizes trust requirements — but you should understand exactly what assumptions remain.
+
+| Component | Trust Assumption | Mitigation |
+| --- | --- | --- |
+| Intel SGX | Hardware integrity of the enclave | Industry standard; used by Fireblocks, Azure confidential computing. Side-channel research is ongoing — see [Research Basis](./research-basis.md). |
+| Oasis Sapphire | Correct implementation of confidential contracts; blockchain liveness | Open-source, audited. Decentralized validator network. Native rollback protections. [Sapphire docs →](https://docs.oasis.io/dapp/sapphire/) |
+| Privana service code | Enclave code does what it claims | Remote attestation allows cryptographic verification of the exact running code. |
+| Privana / Oasis team | Cannot access vault keys | Architecture enforces this — SGX prevents privileged access. Not a promise; a hardware constraint. |
+| Pooled vault model | Users trust the vault's accounting logic to protect all balances correctly | Accounting logic runs inside TEE on Oasis Sapphire. Trust is bounded by TEE + blockchain security model. |
+| Yield protocols | Smart contract risk (Aave at launch) | Only vetted protocols. Yield is opt-in. Automatic unwinding if a protocol is delisted. |
+| DEX execution (Seq. 3) | LiFi aggregator executes as expected | Standard on-chain DEX risk. Slippage protection and spread thresholds enforced in policy. |
+
+Two risks Privana cannot eliminate: (1) vulnerabilities in Intel SGX itself — a class of hardware-level attacks that exist for all TEE platforms, and (2) smart contract bugs in the external yield protocols you choose to use. Both are disclosed openly, and the system mitigates them through conservative platform selection, audits, and protocol vetting.
+
+### Complete Knowledge proofs
+
+The Liquefaction framework discusses **Complete Knowledge (CK) proofs** — cryptographic proofs that a user has unencumbered access to a private key. While Privana implements constructive (beneficial) applications of key encumbrance rather than adversarial ones, CK proofs could become a valuable complement — for example, allowing centralized exchanges to verify that a depositor's keys are not encumbered. The Oasis team is monitoring developments in CK proof practicality, particularly as mobile-TEE attestation hardware matures.

docs/docs/architecture/trust-model.md

@@ -0,0 +1,42 @@
+---
+id: key-encumbrance
+title: "Key Encumbrance"
+sidebar_position: 3
+description: "Define wallet rules once and let the hardware enclave enforce them. Key encumbrance gives you DeFi automation without surrendering your private key."
+---
+
+Traditional wallets require you to manually approve every transaction. Key encumbrance lets you define rules once, and the hardware enclave enforces them automatically — without ever exposing your keys.
+
+In a standard DeFi wallet, you control a private key and must sign every action yourself. This makes automation impossible without handing your key to a third party — which defeats the purpose of self-custody.
+
+**Key encumbrance** breaks this trade-off. It's a concept from the [Liquefaction research paper](https://arxiv.org/abs/2412.02634) by Austgen et al. at Cornell Tech. The idea: a private key is generated and held inside a TEE, and it is governed by **programmable access-control policies** that define exactly what the key is allowed to sign. The key has never existed outside the enclave. It is "encumbered" — it can only act within the bounds of the policies you set.
+
+Instead of signing each transaction yourself, you define a policy once. The enclave then executes on your behalf, but only within those bounds. You can revoke or update the policy at any time.
+
+```js
+// Example policy: delegate yield routing, keep direct swap control
+{
+  asset:            "USDC",
+  spend_limit:      1000 USDC/day,    // max automated spend
+  destination_lock: ["aave-v3"],      // only this protocol
+  expires:          30 days,          // time-bound — auto-expires
+  revocable:        true              // you can always cancel
+}
+
+// The enclave enforces these limits in hardware.
+// No one — including Privana — can execute outside these rules.
+```
+
+### Asset-Time Segmentation
+
+Privana enforces a principle called **Asset-Time Segmentation**: at any given time, a specific asset position is exclusively controlled by one actor — either you directly, or a delegation you've granted. Two policies can never simultaneously claim the same assets. This prevents conflicts and ensures you can always exit — a yield delegation cannot prevent you from withdrawing your funds.
+
+### What this changes
+
+Key encumbrance breaks what cryptographers call the **SEAO assumption** — Single-Entity Address-Ownership. With a standard wallet, one address equals one person who controls it absolutely. With key encumbrance, an address can be governed by complex policy rules: multiple delegations, time bounds, asset limits — all enforced in hardware, all without transferring custody. This is what makes automated, private DeFi possible without giving up control.
+
+:::info[A helpful analogy]
+
+Think of key encumbrance like a power of attorney with strict, hardware-enforced limits. You've given instructions — but those instructions are locked into hardware that even the person holding the power of attorney can't change. And you can revoke it the moment you want.
+
+:::