e4c9dda0fd
Some checks failed
Deploy to Phoenix / deploy (push) Has been cancelled
- Marked submodules ai-mcp-pmm-controller, explorer-monorepo, and smom-dbis-138 as dirty to reflect recent changes. - Updated documentation to clarify operator script usage, including dotenv loading and task execution instructions. - Enhanced the README and various index files to provide clearer navigation and task completion guidance. Made-with: Cursor
106 lines
4.4 KiB
Markdown
106 lines
4.4 KiB
Markdown
# 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.
|