vm-cloud/docs/AKASH_INTEGRATION.md

# Akash Network Integration

## Overview

VaultMesh Cloud CLI integration with [Akash Network](https://akash.network) - a decentralized compute marketplace built on Cosmos blockchain.

## Why Akash?

| Feature | Akash | Traditional Cloud |
|---------|-------|-------------------|
| **Cost** | 60-85% cheaper | Baseline |
| **Model** | Reverse auction marketplace | Fixed pricing |
| **Billing** | AKT tokens per-block | Fiat monthly/hourly |
| **Lock-in** | None - switch providers anytime | Vendor lock-in |
| **Censorship** | Resistant (blockchain) | Subject to provider |

## Architecture

```
┌─────────────────────────────────────────────────────────┐
│                    vmc CLI                              │
├─────────────────────┬───────────────────────────────────┤
│   vmc servers ...   │         vmc akash ...             │
│   (Hetzner)         │         (Akash Network)           │
├─────────────────────┼───────────────────────────────────┤
│   src/lib/hcloud.ts │   src/lib/akash/client.ts         │
│                     │   src/lib/akash/wallet.ts         │
│                     │   src/lib/akash/sdl.ts            │
├─────────────────────┴───────────────────────────────────┤
│              Receipt System (src/lib/receipt.ts)        │
│              Lock System (src/lib/lock.ts)              │
└─────────────────────────────────────────────────────────┘
```

## Akash Concepts

### SDL (Stack Definition Language)

YAML-based deployment specification (like docker-compose):

```yaml
version: "2.0"

services:
  web:
    image: nginx:latest
    expose:
      - port: 80
        as: 80
        to:
          - global: true

profiles:
  compute:
    web:
      resources:
        cpu:
          units: 1
        memory:
          size: 512Mi
        storage:
          - size: 10Gi

  placement:
    akash:
      pricing:
        web: 50uakt  # micro-AKT per block (~6 sec)

deployment:
  web:
    akash:
      profile: web
      count: 1
```

### Deployment Flow

```
1. CREATE DEPLOYMENT
   └─> SDL manifest → Blockchain transaction
   └─> Returns: DSEQ (deployment sequence number)

2. RECEIVE BIDS
   └─> Providers bid on your deployment
   └─> ~15 minutes window

3. ACCEPT BID → CREATE LEASE
   └─> Select provider
   └─> Escrow AKT for payment

4. SEND MANIFEST
   └─> Upload deployment spec to provider
   └─> Provider starts containers

5. MONITOR / UPDATE / CLOSE
   └─> Check status, update resources, or terminate
```

### Key Identifiers

| ID | Description |
|----|-------------|
| `DSEQ` | Deployment sequence number |
| `GSEQ` | Group sequence (usually 1) |
| `OSEQ` | Order sequence (usually 1) |
| `owner` | Wallet address (akash1...) |
| `provider` | Provider address (akash1...) |

## CLI Commands

### Read-Only (Phase 1)

```bash
# List all deployments for configured wallet
vmc akash list

# Get deployment details
vmc akash status <dseq>

# List bids for a deployment
vmc akash bids <dseq>

# Check wallet balance
vmc akash balance
```

### Mutations (Phase 2)

```bash
# Deploy from SDL file
vmc akash deploy --sdl app.yaml --yes --reason "deploy web app"

# Close deployment (refunds remaining escrow)
vmc akash close <dseq> --yes --reason "scaling down"

# Update deployment resources
vmc akash update <dseq> --sdl app.yaml --yes --reason "increase memory"
```

## Configuration

### Environment Variables

```bash
# Required for queries
AKASH_WALLET_ADDRESS=akash1...       # Your wallet address

# Required for mutations
AKASH_MNEMONIC="word1 word2 ... word12"  # 12-word seed phrase

# Optional
AKASH_NETWORK=testnet                 # testnet or mainnet
AKASH_REST_ENDPOINT=https://api.akashnet.net
```

### Testnet vs Mainnet

| Network | Endpoint | Tokens |
|---------|----------|--------|
| Testnet | `https://api.sandbox.akash.network` | Free test AKT |
| Mainnet | `https://api.akashnet.net` | Real AKT |

Get testnet tokens: [Akash Faucet](https://faucet.sandbox.akash.network)

## File Structure

```
src/lib/akash/
├── types.ts        # TypeScript interfaces
├── client.ts       # REST API client
├── wallet.ts       # Mnemonic/signing (Phase 2)
└── sdl.ts          # SDL parsing (Phase 2)

src/commands/akash/
├── list.ts         # List deployments
├── status.ts       # Deployment details
├── bids.ts         # List bids
├── balance.ts      # Wallet balance
├── deploy.ts       # Create deployment (Phase 2)
└── close.ts        # Close deployment (Phase 2)

templates/akash/
├── web.yaml        # Basic web service
├── gpu.yaml        # GPU workload
└── postgres.yaml   # Database with storage
```

## Receipt Structure

Akash mutations produce VaultMesh-grade receipts:

```json
{
  "timestamp": "2025-12-26T18:30:00.000Z",
  "platform": "akash",
  "network": "testnet",
  "action": "deploy",
  "target": {
    "dseq": "12345",
    "owner": "akash1abc...",
    "provider": "akash1xyz..."
  },
  "request": {
    "sdl_hash": "sha256:abc123...",
    "resources": {
      "cpu": 1,
      "memory": "512Mi",
      "storage": "10Gi"
    },
    "max_price": "50uakt"
  },
  "response": {
    "tx_hash": "ABCD1234...",
    "lease_price": {
      "amount": "45",
      "denom": "uakt"
    },
    "status": "active"
  },
  "reason": "deploy web app",
  "sha256": "..."
}
```

## Dependencies

```json
{
  "@akashnetwork/akash-api": "latest",
  "@cosmjs/stargate": "^0.32.0",
  "@cosmjs/proto-signing": "^0.32.0"
}
```

## Resources

- [Akash Network Docs](https://akash.network/docs/)
- [SDL Reference](https://docs.akash.network/readme/stack-definition-language)
- [Awesome Akash (326+ examples)](https://github.com/akash-network/awesome-akash)
- [Akash Console (Web UI)](https://console.akash.network)
- [API Endpoints](https://akash.network/docs/akash-nodes/api-endpoints/)

## Implementation Status

- [ ] Phase 1: Read-only commands (list, status, bids, balance)
- [ ] Phase 2: Wallet signing + mutations (deploy, close, update)
- [ ] Phase 3: SDL templates and validation
- [ ] Phase 4: Multi-cloud abstraction layer