solana-gasless-skill

solana-gasless-skill

A Claude Code / Codex Agent Skill that makes any coding agent an expert at gasless Solana onboarding and account abstraction — and, critically, at building it without getting the sponsor wallet drained.

MIT licensed. Built for the Solana AI Kit skill bounty. Designed to slot in as an ext/ submodule.

The problem it solves

The single biggest reason new users bounce off a Solana app: they don't have SOL, so they can't do anything — not even create the token account needed to receive your token. And even when an app is gasless, the relayer that pays those fees is a high-value attack surface: it's a key that pays for whatever it co-signs. Done naively, it gets drained on day one.

There are skills for transactions, security, payments, and tokenomics — but nothing in the kit or the bounty submissions covers gasless / fee sponsorship / account abstraction. (Verified by scanning all open submissions and the kit's own skill hub.) This fills that gap.

This skill makes the agent produce correct and drain-resistant gasless infrastructure:

• Fee sponsorship — your server pays the SOL fee; the user signs only the message (fee-payer + partial signing).
• Sponsored account creation — pay the rent to create users' ATAs (the real cold-start cost, ~5,000× the base fee), which most "gasless" guides forget.
• Fee-in-token — let users pay fees in USDC / your token instead of SOL (Kora, Octane, Circle Gas Station).
• Session keys — one-tap, no-popup UX for games and AI agents.
• Relayer security ⭐ — the part everyone gets wrong: simulation, deny-by-default instruction allowlists, fee-payer-safety checks, compute/priority caps, rate limiting + auth, balance-delta guards, Lighthouse on-chain assertions, budgets, and a kill switch. This is most of the skill, because it's most of the work.

Why it's production-grade, not a demo

• Grounded in the 2026 stack: Kora (Solana Foundation's modular fee relayer), Octane (anza-xyz/octane), Circle Gas Station, Gum/Magicblock session keys, Lighthouse assertions, versioned transactions, durable nonces, @solana/kit.
• The flagship file is a threat model + non-negotiable checklist with a real policy-gate implementation — assertRelayerWillSign with allowlist, simulation, fee-payer-abuse detection, and balance-delta guard.
• Not just docs — it ships a runnable, tested reference relayer (reference/): the policy gate in TypeScript with a 25-test adversarial suite (drain attempt, token-authority abuse, unlisted program, over-CU, over-budget, replay, rate-limit → all correctly rejected; sponsored happy path → accepted). Hermetic (no network): cd reference && npm install && npm test.
• Ships two commands: /gasless-setup (scaffold a hardened relayer) and /relayer-audit (find drain bugs in an existing one), plus auto-loading rules/relayer-safety.md so the constraints apply every time the agent touches relayer code.
• Progressive disclosure: SKILL.md is a thin router; detail lives in focused files loaded only when needed — token-efficient by design.

Install

Claude Code (recommended):

git clone https://github.com/<you>/solana-gasless-skill.git
cd solana-gasless-skill
./install.sh /path/to/your-project      # copies into .claude/skills/solana-gasless

Codex / Cursor / other agents:

AGENTS_DIR=.agents ./install.sh /path/to/your-project

Manual / as a submodule of the kit:

# from your kit checkout
git submodule add https://github.com/<you>/solana-gasless-skill ext/solana-gasless
# then reference skill/SKILL.md from the kit's skill hub

Restart/reload the agent, then try:

"set up gasless onboarding so my users don't need SOL to claim their first token"

Structure

solana-gasless-skill/
├── skill/
│   ├── SKILL.md             # entry point — frontmatter trigger + routing table
│   ├── fee-payer.md         # the gasless primitive: fee payer + partial signing
│   ├── relayer-security.md  # ⭐ threat model + non-negotiable drain-defense checklist
│   ├── token-fees.md        # pay fees in USDC/SPL — Kora, Octane, Circle
│   ├── sponsored-accounts.md# sponsoring ATA/rent — the real cold-start cost
│   ├── session-keys.md      # one-tap UX for games & agents (Gum/Magicblock)
│   ├── providers.md         # managed vs self-host decision guide
│   ├── testing.md           # adversarial testing & hardening
│   └── resources.md         # curated, current references
├── commands/
│   ├── gasless-setup.md     # /gasless-setup — scaffold a hardened relayer
│   └── relayer-audit.md     # /relayer-audit — audit a relayer for drain bugs
├── agents/
│   └── gasless-engineer.md  # security-first persona for this work
├── rules/
│   ├── relayer-safety.md    # auto-loaded non-negotiable constraints
│   └── typescript.md        # TS conventions for generated code
├── reference/               # runnable, tested reference relayer (25 passing tests)
│   ├── src/                 # gate.ts, feePayerSafety.ts, computeBudget.ts, relayer.ts, ...
│   ├── test/                # adversarial suite (vitest, hermetic)
│   └── README.md            # how it maps to relayer-security.md + how to run
├── install.sh               # one-command install into .claude (or .agents)
├── CLAUDE.md                # config for drop-in use
└── LICENSE                  # MIT

How it routes (progressive disclosure)

SKILL.md loads only its name + description until the agent decides it's relevant, then opens just the focused file the task needs:

Golden rules (enforced by rules/relayer-safety.md)

1. Never co-sign a transaction you didn't simulate successfully.
2. Never co-sign instructions outside an explicit allowlist.
3. The fee payer pays fees and rent — nothing else (no SOL-out, no authority hijack).
4. Always cap compute + priority fee.
5. Always authenticate and rate-limit the sponsor endpoint.
6. Never commit a fee-payer keypair; small hot balance + daily cap + kill switch.
7. Session keys are least-privilege: narrow scope, short expiry, revocable.

License

MIT — free to merge or submodule into the Solana AI Kit.

Acknowledgements

References Solana Foundation docs/cookbook, Kora, Anza's Octane, Circle Gas Station, Gum/Magicblock session keys, and Lighthouse. See skill/resources.md.