Feat: x402 Gas Abstraction Gateway

.changeset/plenty-states-camp.md

@@ -0,0 +1,16 @@
+---
+"@darkresearch/mallory-client": minor
+"@darkresearch/mallory-server": minor
+---
+
+Add x402 gas abstraction feature with balance caching, top-up, and transaction sponsorship
+
+- Implement wallet authentication generator for gateway authentication
+- Add x402 gas abstraction service with balance query, top-up, and transaction sponsorship
+- Add client-side gas abstraction context with 10-second balance caching
+- Implement gas abstraction screen UI with balance display, top-up flow, and transaction history
+- Add developer API for agents (GasSponsorClient)
+- Integrate gasless mode for AI tool transactions and SendModal
+- Add comprehensive test coverage (unit, integration, and E2E tests)
+- Add telemetry logging for gas abstraction operations
+- Support graceful degradation with SOL fallback

.cursor/rules/logs.mdc

@@ -0,0 +1,7 @@
+---
+alwaysApply: true
+---
+
+Log every error we encounter in a file called logs.md and add a timestamp to the error.
+whenever we encounter an error, you source of truth is the logs.md file.
+to check if we already encountered the same error, so we never loop again in the same cycle of errors.

.cursor/rules/x402gasabstraction.mdc

@@ -0,0 +1,89 @@
+---
+alwaysApply: true
+---
+# =========================================
+# CURSOR GLOBAL RULES — Mallory Gas Abstraction Development
+# =========================================
+
+# SOURCE OF TRUTH
+1. The following documents are the SINGLE authoritative specification:
+   - .kiro/specs/x402_gas_abstraction/requirements.md
+   - .kiro/specs/x402_gas_abstraction/design.md
+   - .kiro/specs/x402_gas_abstraction/tasks.md
+   Cursor must ALWAYS read these files before implementing anything.
+
+2. No deviation is allowed:
+   - Do not invent features.
+   - Do not simplify flows.
+   - Do not remove constraints, validations, retries, or error-handling steps
+     specified in requirements.md or design.md or tasks.md.
+   - If something is unclear, prefer the spec over assumptions.
+
+# WORKFLOW RULES
+3. Cursor must work IN SMALL TASK GROUPS (1–3 sub-tasks at a time).
+4. For each cycle:
+   - Identify the next tasks marked `[ ]` in tasks.md.
+   - Present a short plan for those tasks.
+   - Ask for approval before modifying code.
+   - After approval, implement changes with minimal diffs.
+   - Run typecheck, lint, tests.
+   - Propose a git commit.
+   - Update tasks.md by checking off completed items.
+
+5. ALWAYS maintain a buildable repo:
+   - Every commit must compile.
+   - Every commit must pass tests.
+   - Never leave failing or partial work uncommitted.
+
+# CODE QUALITY RULES
+6. Follow existing Mallory architecture and conventions:
+   - Use existing Solana helpers.
+   - Use existing Grid context helpers.
+   - Respect file naming.
+   - Respect folder structure.
+
+7. Keep code DRY and modular:
+   - Don’t duplicate logic that already exists elsewhere.
+   - Implement new modules (auth generator, abstraction service, context, screens)
+     only in designated directories.
+
+8. All TypeScript code must be fully typed.
+9. NEVER rewrite entire files if diff-based patching is possible.
+
+# FEATURE GUARANTEES
+10. Gas abstraction MUST:
+    - Support balance caching (10 sec)
+    - Support top-up via x402 payload
+    - Support sponsored tx flow
+    - Respect SOL fallback behavior
+    - Support telemetry logging
+    - Support error handling for:
+      - 402 insufficient balance
+      - 400 old blockhash
+      - 400 prohibited instruction
+      - 401 stale auth retry
+      - 503 temporary outage
+    - Integrate with agents (developer API)
+    - Provide UI screens
+    - Support low-balance banners
+    - Be disabled via feature flag
+
+# TESTING RULES
+11. Write tests for modules marked with `*` in tasks.md.
+12. Do not skip tests unless the spec explicitly allows it.
+13. When updating tasks.md, keep starred tasks clearly marked.
+
+# COMMITS
+14. Commit messages MUST be conventional:
+    - feat(gas): ...
+    - fix(gas): ...
+    - refactor(gas): ...
+    - chore(gas): ...
+    - docs(gas): ...
+
+15. Each commit must:
+    - Contain 1–3 completed tasks.
+    - Be atomic and revertible.
+    - Pass tests and linting.
+
+# END OF RULES

.env.test.example

@@ -0,0 +1,32 @@
+# Test Environment Variables Example
+# Copy this file to .env.test and fill in your actual values
+# DO NOT commit .env.test to version control
+
+# Test Wallet Address (Grid wallet with USDC for testing)
+TEST_WALLET_ADDRESS=YOUR_WALLET_ADDRESS_HERE
+
+# Grid Session Account (JSON string)
+# Get this from browser localStorage using get-grid-session.js
+# Format: {"address":"...","policies":{...},"grid_user_id":"...","authentication":[...]}
+TEST_GRID_ACCOUNT=
+
+# Grid Session Secrets (JSON array string)
+# Get this from browser localStorage using get-grid-session.js
+# Format: [{"publicKey":"...","privateKey":"...","provider":"...","tag":"..."},...]
+TEST_GRID_SESSION_SECRETS=
+
+# Test Supabase Credentials (for authentication)
+TEST_SUPABASE_EMAIL=your-test-email@example.com
+TEST_SUPABASE_PASSWORD=your-test-password
+
+# Backend URL for testing
+TEST_BACKEND_URL=http://localhost:3001
+
+# Solana RPC URL (optional, will use public endpoints if not set)
+SOLANA_RPC_URL=
+
+# Alchemy RPC URLs (optional, used as fallbacks)
+# Get these from your Alchemy dashboard - these are private API keys
+SOLANA_RPC_ALCHEMY_1=
+SOLANA_RPC_ALCHEMY_2=
+SOLANA_RPC_ALCHEMY_3=