Gas & Wallet Economics

About

How token economics work on Tawa — pod pricing, the deploy gate, gas metering, and wallet management.

Skill Content

This is the raw markdown that gets installed as a Claude Code rule.

# Gas & Wallet Economics

## What this skill covers
How token economics work on Tawa — pod pricing, the deploy gate, gas metering, and wallet management.

## Token Basics

- 1 gas token = $0.01 USD
- New accounts receive 50,000 free intro tokens
- Tokens pay for two things: **hosting** (pod uptime) and **transactions** (API calls)
- Token spend order: intro tokens first, then purchased, then earned

## Pod Tiers and Pricing

| Tier | CPU | Memory | Gas/Hour | Gas/Month | USD/Month |
|------|-----|--------|----------|-----------|-----------|
| nano | 0.25 | 256Mi | 5 | 3,600 | $36 |
| small | 0.5 | 512Mi | 10 | 7,200 | $72 |
| medium | 1 | 1Gi | 23 | 16,560 | $165.60 |
| large | 2 | 2Gi | 42 | 30,240 | $302.40 |
| xlarge | 4 | 4Gi | 83 | 59,760 | $597.60 |

Set pod tier in catalog-info.yaml:
```yaml
metadata:
  annotations:
    insureco.io/pod-tier: "nano"    # Default if not specified
```

**The tier is enforced as real container resources.** On deploy the builder sets
the pod's Kubernetes `resources.limits` to the tier's CPU/Memory above (and
`resources.requests` to ~50% of the limit, so pods stay burstable and packable).
This means the size you pick is the size you get — the tier's gas rate and its
actual CPU/Memory are the same knob. Bumping the tier raises both the cost **and**
the pod's real ceiling; lowering it does the reverse. An unknown tier falls back
to `nano` with a build warning. The namespace `LimitRange` max is `4 CPU / 4Gi`
(xlarge), so no tier is capped below its declared size.

> A pod stuck slow/CPU-throttled is usually under-tiered — raise `pod-tier` and
> redeploy. Before this enforcement (builder < 0.6.x) every pod got a flat
> `500m/512Mi` regardless of tier; if a service was silently relying on that,
> pick the tier that matches its real need (`small` = the old default).

## Deploy Gate

Before every build, the builder checks your wallet has enough gas to cover 3 months of hosting:

```
Required reserve = hostingGasPerHour × 24 × 30 × 3
```

For a nano pod: 5 × 24 × 30 × 3 = 10,800 tokens ($108)

If you also declare `spec.storage`, the gate adds **3 months of storage gas** on top:

```
Required reserve = (hostingGasPerHour × 24 × 30 × 3) + (storageGasPerMonth × 3)
```

If your wallet balance is below the reserve, the deploy is blocked with:
> "Deploy gate: insufficient gas reserve"

The deploy gate runs two more hard-fail checks before the reserve check:

- **Org allowlist** — `spec.owner` must be in the approved-orgs list (`ALLOWED_DEPLOY_ORGS`, default `insureco`).
- **Owner tamper guard** — `spec.owner` must match the registered service owner, so a deploy can't charge another org's wallet.

### Platform Services Skip the Gate
These services bypass the deploy gate: iec-wallet, iec-janus, tawa-web, koko, bio-id, iec-test.

### Gate is Fail-Open
If the wallet service is unreachable, deploys proceed anyway (resilience over strictness).

## Gas Metering via Janus

Janus tracks two types of gas events:

| Type | Charged For | Example |
|------|-------------|---------|
| **hosting** | Pod uptime per hour | Running my-api on nano tier |
| **transaction** | API calls through Koko | GET /api/users (5 gas) |

Transaction gas is only charged on successful (2xx) responses.

## Wallet Operations

```bash
# Check your balance
tawa wallet

# Buy more tokens
tawa wallet buy 10000

# View gas spending
tawa gas
```

## Key Facts
- Start with nano tier — it's enough for most services and keeps gas costs low
- The 50,000 intro tokens cover ~13 months of a nano pod
- Deploy gate checks happen BEFORE the Docker build (saves time on failures)
- Gas events are scoped by org — each org sees only their own usage
- Pod tier is the single biggest factor in your monthly cost

Install

Copy the skill content and save it to:

~/.claude/rules/tawa-gas-wallet.md

Details

Format

Rule

Category

provision

Version

1.0.95986

Tokens

~935

Updated

2026-08-28