# Alltra (651940) Gas Sponsorship — Policy Matrix and Method Allowlist

**Purpose:** Define the sponsorship policy for Alltra-native gas (ERC-4337 paymaster on chain 651940): three-tier policy, method allowlist, and anti-abuse controls. Use with thirdweb Engine or an ERC-4337 paymaster contract on 651940.

**References:** [thirdweb Gas Sponsorship](https://portal.thirdweb.com/wallets/sponsor-gas), [ERC-4337 Paymasters](https://docs.erc4337.io/paymasters/index.html), [THIRDWEB_ENGINE_CHAIN_OVERRIDES.md](THIRDWEB_ENGINE_CHAIN_OVERRIDES.md).

---

## 1. Policy groups

### Policy Group 1 — Always sponsor (low risk, onboarding)

| Category | Contract | Allowed methods | Notes |
|----------|----------|-----------------|-------|
| Smart account init | AA factory / account | `createAccount`, `initialize` | Required for first use |
| Session / auth proofs | Auth/Session contract (if onchain) | `registerKey`, `rotateKey` | If keys stored onchain |
| First app action | CoreApp contract (TBD) | 1–2 core functions | Keep small initially |

### Policy Group 2 — Sponsor with caps (medium risk)

| Category | Contract | Allowed methods | Caps |
|----------|----------|-----------------|------|
| App events writes | CoreApp / Modules | Selected write funcs | Per-user/day tx limit + per-user/day gas limit |
| Claims / mints | Token/NFT drop | `claim`, `mintTo` | Restrict to allowlisted drops only |

### Policy Group 3 — Do not sponsor (high risk)

- Arbitrary `approve()` to unknown spenders
- Arbitrary ERC-20 `transfer` / `transferFrom`
- Swaps and bridge calls (user pays gas)

---

## 2. Anti-abuse controls (minimum viable)

- **Per-user daily max sponsored gas** — e.g. 500k gas/day per wallet.
- **Per-IP / per-device burst limits** — e.g. max N requests per minute from same IP.
- **Contract allowlist only** — only contracts in the allowlist can be called in sponsored userOps.
- **Method allowlist only** — only method selectors in the allowlist (see below) are sponsored.
- **Optional:** After first N sponsored tx, require user to hold a small amount of native gas token before further sponsorship.

---

## 3. Method allowlist (production)

Configure the paymaster with a **method allowlist** keyed by `(chainId, contract, method selector)`.

**Chain:** 651940 (Alltra).

**Contract + method selectors:** To be filled when CoreApp (and optional AA factory, session contract) addresses and method names are known. Example shape:

| Contract (address) | Method | Selector (4 bytes) | Policy group |
|--------------------|--------|---------------------|--------------|
| TBD (CoreApp) | `doAction` | `0x...` | 1 or 2 |
| TBD (AA factory) | `createAccount` | `0x...` | 1 |
| TBD (AA factory) | `initialize` | `0x...` | 1 |

**How to add selectors:** For each method, compute `keccak256(methodSignature).slice(0, 10)` (e.g. `doAction(uint256)` → selector). Paste into Engine paymaster policy or into your paymaster contract’s allowlist.

**Placeholder JSON (allowlist):** When you have contract addresses and method names, add a file e.g. `config/alltra-sponsorship-allowlist.json`:

```json
{
  "chainId": 651940,
  "contracts": [
    {
      "address": "0x...",
      "label": "CoreApp",
      "methods": [
        { "name": "doAction", "selector": "0x..." }
      ]
    }
  ]
}
```

---

## 4. Per-user / per-day caps (recommended values)

| Limit | Suggested value | Notes |
|-------|------------------|-------|
| Sponsored gas per user per day | 500_000 | Tune for your app |
| Sponsored tx count per user per day | 10 | For Group 2 |
| Burst (per IP) | 20 req/min | Rate limit |

---

## 5. Implementation checklist

- [ ] Add chain 651940 to Engine (see [THIRDWEB_ENGINE_CHAIN_OVERRIDES.md](THIRDWEB_ENGINE_CHAIN_OVERRIDES.md)).
- [ ] Create or configure paymaster on 651940 (thirdweb Engine or custom contract).
- [ ] Set Policy Group 1 contracts and method selectors (AA init, optional session).
- [ ] Set Policy Group 2 contracts and method selectors (CoreApp, claims) with per-user/day caps.
- [ ] Enforce contract + method allowlist; reject all other calls.
- [ ] Add per-user daily gas and tx limits; optional per-IP burst limit.

---

## 6. Separation from x402

- **Sponsorship:** Pays for **gas** of user’s app actions (onchain writes) on 651940.
- **x402:** User pays **USDC** for API/service access (offchain response gated by onchain payment proof).

They are independent: x402 payment is a user-funded USDC transfer; sponsored txs are paymaster-funded gas.