MORP OS Documentation

Private Finance Operating System on Solana. Non-custodial privacy layer for payments, swaps, and portfolio management.

🛡️

Shadow Balances

🔐

ZK Commitments

👻

Stealth Payments

📊

Private Analytics

Core Features

Shadow Balances - Balances hidden from public blockchain explorers
Stealth Payments - Private P2P transfers with claim codes via escrow
ZK Commitment Scheme - Optional maximum privacy mode hiding amounts
Selective Disclosure - Generate cryptographic proofs for auditors
Batch Processing - Transactions grouped to obscure individual activity
Non-Custodial - Users sign all transactions client-side

Architecture

Technology Stack

Layer	Technology
Frontend	React, TailwindCSS, Shadcn/UI
Wallet	@solana/wallet-adapter (Phantom, Solflare)
State	TanStack Query v5
Backend	Express.js, TypeScript
Database	PostgreSQL + Drizzle ORM
Blockchain	Solana, Jupiter DEX

Key Components

Project Structure

├── client/src/
│   ├── pages/
│   │   ├── dashboard.tsx    # Portfolio overview
│   │   ├── swap.tsx         # Jupiter DEX integration
│   │   ├── stealth.tsx      # Private payments
│   │   ├── portfolio.tsx    # Holdings & positions
│   │   ├── analytics.tsx    # P&L charts
│   │   ├── yield.tsx        # Yield farming
│   │   ├── disclosure.tsx   # Selective proofs
│   │   └── compliance.tsx   # Audit trail
│   └── components/
│       ├── wallet-provider.tsx
│       └── privacy-shield.tsx
├── server/
│   ├── routes.ts           # API endpoints
│   ├── storage.ts          # Database operations
│   ├── solana.ts           # RPC & transactions
│   └── zk-commitment.ts    # ZK crypto functions
└── shared/
    └── schema.ts           # Data models

Stealth Payments

Stealth payments enable private peer-to-peer token transfers where there is no direct blockchain link between sender and recipient.

Escrow Flow

Sender Deposits to Escrow

Sender signs transaction transferring tokens to platform escrow wallet. Transaction signed client-side (non-custodial).

↓

Claim Code Generated

System generates unique claim code. Sender shares this code with recipient off-chain (chat, email, etc).

↓

Recipient Claims

Recipient enters claim code. Server verifies and releases tokens from escrow to recipient's wallet.

ℹ️

Non-Custodial Design

Sender signs their own deposit transactions. Escrow only holds tokens temporarily until claimed.

ZK Commitment Scheme

Optional maximum privacy mode that hides payment amounts using SHA-256 cryptographic commitments.

How It Works

Sender Enables ZK Mode

Toggle "ZK Privacy Mode" when creating payment. System generates secret and salt.

↓

Commitment Created

commitment = SHA-256(amount + secret + salt)
Only the hash is stored, NOT the actual amount.

↓

Sender Receives ZK Claim Data

JSON with code, amount, and secret. Must be shared off-chain with recipient.

↓

Recipient Provides Proof

Recipient must enter the correct amount + secret. Server verifies hash matches before releasing tokens.

ZK Claim Data Format

JSON

{
  "code": "abc123xyz789",
  "amount": "10.5",
  "secret": "randomSecret456"
}

Verification Process

TypeScript

// Server-side verification
function verifyZkCommitment(
  storedCommitment: string,
  providedAmount: string,
  providedSecret: string,
  storedSalt: string
): boolean {
  const dataToHash = `${providedAmount}:${providedSecret}:${storedSalt}`;
  const computedHash = sha256(dataToHash);
  return computedHash === storedCommitment;
}

⚠️

Important

If ZK claim data is lost, tokens cannot be recovered. The amount is not stored anywhere - only the cryptographic hash exists.

Privacy Scope

🚨

Critical Limitation

MORP OS provides database/application-level privacy, NOT full on-chain anonymity. Transactions remain visible on Solana block explorers like Solscan.

What Is Visible On-Chain (Solscan)

Transaction	Sender Address	Recipient Address	Amount	Timestamp
Sender → Escrow	✗ Visible	Escrow (shared)	✗ Visible	✗ Visible
Escrow → Recipient	Escrow (shared)	✗ Visible	✗ Visible	✗ Visible

What Is Protected

Location	Amount Hidden?	Link Broken?
MORP OS Database	✓ Yes (ZK mode)	✓ Yes
MORP OS API	✓ Yes (ZK mode)	✓ Yes
Off-chain Sharing	✓ Only sender/recipient know	✓ Yes
Blockchain/Solscan	✗ No	✗ No (via escrow timing)

Current Limitations

All transactions visible on Solana explorers with full amounts
Shared escrow wallet creates timing correlation between deposits and claims
Recipient address exposed at claim time
No mixing or routing through multiple addresses

Future Improvements (Possible)

Light Protocol - ZK compressed accounts for true on-chain privacy
Token-2022 Confidential Transfer - Solana's native privacy extension
One-time Escrow - Generate new escrow address per payment
Timing Obfuscation - Random delays between deposit and claim

API Reference

Stealth Payment Endpoints

GET /api/stealth/escrow

Get the escrow wallet public address.

Response:

{ "escrowAddress": "EscrowWallet..." }

POST /api/stealth/build-deposit

Build unsigned deposit transaction for wallet signing.

Request:

{
  "senderWallet": "SenderPublicKey...",
  "tokenMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "amount": "10.5",
  "zkEnabled": true  // Optional: enable ZK mode
}

Response:

{
  "transaction": "base64EncodedTx...",
  "claimCode": "abc123xyz",
  "zkSecret": "randomSecret456"  // Only if zkEnabled
}

POST /api/stealth/build-claim

Build claim transaction. For ZK payments, must include proof.

Request:

{
  "claimCode": "abc123xyz",
  "claimerWallet": "RecipientPublicKey...",
  "zkProof": {           // Required for ZK payments
    "amount": "10.5",
    "secret": "randomSecret456"
  }
}

Response:

{
  "success": true,
  "transaction": "base64EncodedTx...",
  "amount": "10.5",
  "tokenSymbol": "USDC",
  "zkVerified": true
}

GET /api/stealth/lookup/:claimCode

Look up payment details by claim code. Amount hidden for ZK payments.

Response (ZK Payment):

{
  "id": "payment-id",
  "tokenSymbol": "USDC",
  "amount": null,        // Hidden for ZK
  "status": "pending",
  "zkEnabled": true,
  "zkCommitment": "sha256hash...",
  "requiresZkProof": true
}

Portfolio Endpoints

GET /api/portfolio/holdings?wallet=...

Get token holdings with shadow/public balance split.

GET /api/portfolio/stats?wallet=...

Get portfolio statistics (total value, shadow value, etc).

Security Model

Non-Custodial Guarantees

All deposit transactions signed by user's wallet client-side
Private keys never leave user's wallet
Phantom/Solflare manifest for trusted dApp recognition
Transaction simulation before signing

Escrow Security

Escrow private key stored in encrypted Replit Secrets
Server only releases funds on valid claim code (and ZK proof if enabled)
Cancellation returns funds to original sender
Expiration mechanism for unclaimed payments

ZK Commitment Security

SHA-256 cryptographic hash function
Random salt prevents rainbow table attacks
Amount never stored - only the hash commitment
Invalid proofs rejected with clear error message

✅

Audit Trail

All actions generate cryptographic audit entries for compliance and selective disclosure.