@kadi.build/deploy-ability 0.0.1

package/docs/PLACEMENT.md

@@ -0,0 +1,433 @@
+## Understanding Placement Attributes
+
+When deploying to Akash Network, you might want to control **where** your deployment runs geographically. Placement attributes let you specify provider requirements like region, facility type, timezone, and more.
+
+### Why Use Placement Attributes?
+
+**Common Use Cases:**
+
+| Use Case | Example | Placement Attributes |
+|----------|---------|---------------------|
+| **Data Residency** | EU data must stay in EU | `country: "DE"` (Germany) |
+| **Latency Optimization** | Serve US West Coast users | `location-region: "na-us-west"` |
+| **Infrastructure Quality** | Production workloads | `location-type: "datacenter"` |
+| **Cost Optimization** | Testing/development | `location-type: "home"` (cheaper) |
+| **Compliance** | GDPR, data sovereignty | `country: "US"`, `location-region: "eu-west"` |
+
+### Available Placement Attributes
+
+#### Geographic Region (`location-region`)
+
+**Based on UN Geoscheme** - Controls which geographic area your deployment runs in.
+
+**Common Regions:**
+
+| Region | Coverage | Use For |
+|--------|----------|---------|
+| `na-us-west` | US West Coast (CA, OR, WA, etc.) | Low latency to West Coast users |
+| `na-us-east` | US East Coast (NY, MA, VA, etc.) | Low latency to East Coast users |
+| `eu-west` | Western Europe (FR, UK, NL, etc.) | GDPR compliance, EU users |
+| `eu-central` | Central Europe (DE, AT, CH, etc.) | Central EU data residency |
+| `as-east` | Eastern Asia (CN, JP, KR, etc.) | Asian market |
+| `as-southeast` | Southeast Asia (SG, TH, VN, etc.) | Southeast Asian users |
+
+**Total: 48 regions available** - See `AKASH_REGIONS` constant for complete list.
+
+#### Location Type (`location-type`)
+
+**Defines the facility infrastructure quality** - Critical for production vs development.
+
+| Type | Infrastructure | Reliability | Cost | Use For |
+|------|---------------|-------------|------|---------|
+| `datacenter` | Professional datacenter | Enterprise-grade | Higher | Production workloads |
+| `colo` | Co-location facility | High | Moderate | Production, cost-conscious |
+| `server-room` | Dedicated server room | Good | Moderate | Development, staging |
+| `office` | Office-based server | Variable | Lower | Testing |
+| `home` | Home-based server | Variable | Lowest | Development only |
+| `mix` | Mixed infrastructure | Variable | Variable | Flexible requirements |
+
+**Recommendation:** Use `datacenter` for production, `colo` for balanced cost/performance.
+
+#### Timezone (`timezone`)
+
+**UTC offset where provider is located** - Useful for business hours alignment or specific geographic targeting.
+
+**Examples:**
+
+| Timezone | Location | Example Cities |
+|----------|----------|----------------|
+| `utc-8` | US Pacific | San Francisco, Seattle, Los Angeles |
+| `utc-5` | US Eastern | New York, Miami, Toronto |
+| `utc+0` | GMT | London, Dublin, Lisbon |
+| `utc+1` | Central Europe | Paris, Berlin, Rome |
+| `utc+8` | China/Singapore | Beijing, Singapore, Hong Kong |
+| `utc+9` | Japan/Korea | Tokyo, Seoul |
+
+**Total: 27 timezones available** from `utc-12` to `utc+14`.
+
+#### Country (`country`)
+
+**ISO 3166 Alpha-2 country code** - Most specific geographic constraint for strict data residency.
+
+**Examples:** `US`, `DE`, `JP`, `GB`, `FR`, `CA`, `AU`, `SG`
+
+**Use for:** Strict compliance requirements (GDPR, data sovereignty laws).
+
+#### City (`city`)
+
+**City name** - Ultra-specific location targeting.
+
+**Examples:** `San Francisco`, `London`, `Tokyo`, `Berlin`
+
+**Use for:** Ultra-low latency to specific cities or very specific data residency needs.
+
+### Configuration Examples
+
+#### Example 1: US West Coast Production Deployment
+
+```json
+{
+  "deploy": {
+    "production-us-west": {
+      "target": "akash",
+      "network": "mainnet",
+      "placement": {
+        "location-region": "na-us-west",
+        "location-type": "datacenter"
+      },
+      "services": {
+        "api": {
+          "image": "my-api:latest",
+          "resources": { ... }
+        }
+      }
+    }
+  }
+}
+```
+
+**Why:** Professional datacenter on US West Coast for low latency to California/Oregon/Washington users.
+
+---
+
+#### Example 2: EU Data Residency (GDPR Compliance)
+
+```json
+{
+  "deploy": {
+    "production-eu": {
+      "target": "akash",
+      "network": "mainnet",
+      "placement": {
+        "location-region": "eu-west",
+        "location-type": "datacenter",
+        "country": "DE"
+      },
+      "services": {
+        "api": {
+          "image": "my-api:latest",
+          "resources": { ... }
+        }
+      }
+    }
+  }
+}
+```
+
+**Why:** Ensures deployment stays in Germany (strict GDPR compliance) in professional datacenter.
+
+---
+
+#### Example 3: Cost-Optimized Development
+
+```json
+{
+  "deploy": {
+    "dev-cheap": {
+      "target": "akash",
+      "network": "testnet",
+      "placement": {
+        "location-type": "home"
+      },
+      "services": {
+        "api": {
+          "image": "my-api:dev",
+          "resources": { ... }
+        }
+      }
+    }
+  }
+}
+```
+
+**Why:** Home-based providers are cheaper - perfect for development/testing where uptime isn't critical.
+
+---
+
+#### Example 4: Multi-Region Setup
+
+```json
+{
+  "deploy": {
+    "us-west": {
+      "target": "akash",
+      "network": "mainnet",
+      "placement": {
+        "location-region": "na-us-west",
+        "location-type": "datacenter"
+      },
+      "services": { ... }
+    },
+    "eu-central": {
+      "target": "akash",
+      "network": "mainnet",
+      "placement": {
+        "location-region": "eu-central",
+        "location-type": "datacenter"
+      },
+      "services": { ... }
+    },
+    "asia-east": {
+      "target": "akash",
+      "network": "mainnet",
+      "placement": {
+        "location-region": "as-east",
+        "location-type": "datacenter"
+      },
+      "services": { ... }
+    }
+  }
+}
+```
+
+**Why:** Deploy same application to three regions for global coverage - users connect to nearest region.
+
+---
+
+#### Example 5: Timezone-Based Deployment
+
+```json
+{
+  "deploy": {
+    "business-hours-us": {
+      "target": "akash",
+      "network": "mainnet",
+      "placement": {
+        "timezone": "utc-5",
+        "location-type": "datacenter"
+      },
+      "services": { ... }
+    }
+  }
+}
+```
+
+**Why:** Provider operates during US Eastern business hours - useful for support SLAs.
+
+### How Placement Works
+
+When you specify placement attributes, Akash providers advertise their attributes on-chain. Your deployment includes these requirements in the SDL, and **only providers matching ALL specified attributes** will bid on your deployment.
+
+**Matching Logic:**
+- If you specify `location-region: "na-us-west"` → Only providers in US West bid
+- If you add `location-type: "datacenter"` → Only US West datacenters bid
+- If you add `country: "US"` → Only US West datacenters in the US bid
+
+**Think of it as filtering** - each attribute narrows down the provider pool.
+
+### Common Mistakes
+
+**Over-constraining**
+```json
+{
+  "placement": {
+    "location-region": "na-us-west",
+    "location-type": "datacenter",
+    "country": "US",
+    "city": "San Francisco",
+    "timezone": "utc-8"
+  }
+}
+```
+
+**Problem:** Too specific - you might get zero bids!
+
+**Start broad, narrow as needed**
+```json
+{
+  "placement": {
+    "location-region": "na-us-west",
+    "location-type": "datacenter"
+  }
+}
+```
+
+**Why:** Good balance - ensures West Coast datacenter without being too restrictive.
+
+---
+
+**Conflicting constraints**
+```json
+{
+  "placement": {
+    "location-region": "eu-west",  // Europe
+    "country": "US"                 // United States
+  }
+}
+```
+
+**Problem:** No provider can be in both Europe and US! Zero bids.
+
+**Consistent constraints**
+```json
+{
+  "placement": {
+    "location-region": "eu-west",
+    "country": "GB"  // UK is in eu-west
+  }
+}
+```
+
+---
+
+**Using wrong country code format**
+```json
+{
+  "placement": {
+    "country": "USA"  // Wrong - should be 2-letter code
+  }
+}
+```
+
+**ISO 3166 Alpha-2**
+```json
+{
+  "placement": {
+    "country": "US"  // Correct - 2 letters
+  }
+}
+```
+
+### Validation & Error Messages
+
+deploy-ability validates placement attributes with **helpful error messages**:
+
+**Invalid Region:**
+```
+Invalid region "us-west". Valid regions include: na-us-west, na-us-east, eu-west,
+   eu-central, as-east... (48 total regions available). See AKASH_REGIONS constant for full list.
+```
+
+**Invalid Location Type:**
+```
+Invalid location type "data-center". Valid types: datacenter, colo, home, office, server-room, mix
+```
+
+**Invalid Country Code:**
+```
+Country code must be exactly 2 characters (ISO 3166 Alpha-2 format, e.g., "US", "DE", "JP")
+```
+
+**Unknown Attribute:**
+```
+Unknown placement attribute. Valid attributes: location-region, location-type, timezone, country, city
+```
+
+### TypeScript Support
+
+Full TypeScript support with autocomplete and validation:
+
+```typescript
+import type { AkashPlacementAttributes } from 'deploy-ability';
+
+const placement: AkashPlacementAttributes = {
+  'location-region': 'na-us-west',  // Autocomplete with all 48 regions
+  'location-type': 'datacenter',     // Autocomplete with all 6 types
+  timezone: 'utc-8',                 // Autocomplete with all 27 timezones
+  country: 'US',                     // String, but validated at runtime
+  city: 'San Francisco'              // Optional, free-form string
+};
+```
+
+**Constants Available:**
+```typescript
+import {
+  AKASH_REGIONS,
+  AKASH_LOCATION_TYPES,
+  AKASH_TIMEZONES,
+  getAkashRegions,
+  getAkashLocationTypes,
+  getAkashTimezones
+} from 'deploy-ability';
+
+// Get all regions as array
+const allRegions = getAkashRegions();
+console.log(allRegions.length); // 48
+
+// Get region description
+console.log(AKASH_REGIONS['na-us-west']);
+// "North America - US West (CA, OR, WA, ID, MT, WY, UT, CO, NV, AK, HI)"
+```
+
+### Advanced: Combining with Other Attributes
+
+Placement attributes work alongside other provider requirements:
+
+```json
+{
+  "deploy": {
+    "gpu-production": {
+      "target": "akash",
+      "network": "mainnet",
+      "placement": {
+        "location-region": "na-us-west",
+        "location-type": "datacenter"
+      },
+      "attributes": {
+        "gpu": "nvidia"
+      },
+      "signedBy": {
+        "allOf": ["akash1365yvmc4s7awdyj3n2sav7xfx76adc6dnmlx63"]
+      },
+      "services": {
+        "ml-inference": {
+          "image": "my-llm:latest",
+          "resources": {
+            "cpu": 4,
+            "memory": "16Gi",
+            "ephemeralStorage": "10Gi",
+            "gpu": {
+              "units": 1,
+              "attributes": {
+                "vendor": {
+                  "nvidia": [{ "model": "rtx4090" }]
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+**Result:** Only US West datacenters with NVIDIA RTX 4090 GPUs, certified by Akash auditor.
+
+### Quick Decision Guide
+
+**Use this flowchart to decide which placement attributes you need:**
+
+```
+Does location matter?
+├─ No → Omit placement (cheapest, fastest bids)
+├─ Yes → What's most important?
+   ├─ Data residency/compliance → Set `country` + `location-type: datacenter`
+   ├─ Low latency to users → Set `location-region` close to users
+   ├─ Infrastructure quality → Set `location-type: datacenter` or `colo`
+   ├─ Cost optimization → Set `location-type: home` (dev only!)
+   └─ Multiple requirements → Combine attributes (but don't over-constrain!)
+```
+
+---
+