Feat: x402 Gas Abstraction Gateway #109
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- Add WalletAuthGenerator with Ed25519 signing for x402 gateway - Implement UUIDv4 nonce generation and base58 signature encoding - Add gas abstraction configuration loading and validation - Integrate config validation into server startup - Add tweetnacl dependency for Ed25519 message signing Completes tasks 1, 2.1, 2.2
- Add X402GasAbstractionService with all TypeScript interfaces - Implement balance query with authentication and retry logic - Implement top-up requirements and submission methods - Implement transaction sponsorship method - Add comprehensive error handling (402, 400, 401, 503) - Add network/asset validation and base unit conversion helpers - Support 401 retry with fresh signature Completes tasks 3.1, 3.2, 3.3, 3.4, 3.5, 3.6, 3.7
- Add telemetry logging utility with gas abstraction event helpers - Create gas abstraction API routes (balance, topup, sponsor) - Integrate telemetry logging into all endpoints - Add comprehensive error handling with GatewayError - Register routes in server with endpoint documentation Completes tasks 4.1, 4.2, 4.3, 4.4, 5.1, 5.2, 5.3, 5.4, 5.5, 5.6
- Add optional server-side top-up helper using ephemeral wallet - Integrate with existing EphemeralWalletManager and Grid sender - Add blockhash refresh utilities for handling expired blockhashes - Note: Full transaction rebuild should be done client-side Completes tasks 6.1, 6.2, 6.3, 7.1
- Add GAS_ABSTRACTION_ENABLED flag (default: false) - Add GAS_ABSTRACTION_DEFAULT_ENABLED flag - Add low balance threshold (0.1 USDC) - Add top-up amount limits (min: 0.5, max: 100, suggested: 5.0 USDC) - Create utility functions for feature flag checks - Support environment variable and Expo config overrides Completes tasks 8.1, 8.2
- Create GasAbstractionContext with full state management - Implement balance fetching with 10-second staleness check - Add automatic refresh on app focus - Implement transaction sponsorship with error handling - Add gasless mode toggle with AsyncStorage persistence - Implement low balance detection - Add computed values (pendingAmount, availableBalance) - Change balance endpoint to POST (Grid session in body) Completes tasks 9.1, 9.2, 9.3, 9.4, 9.5, 9.6, 9.7
- Create GasSponsorClient interface with typed methods - Implement getBalance, topup (placeholder), sponsorTransaction - Add agent tools for LLM invocation (check_gas_balance, sponsor_and_send_transaction) - Provide clear error messages for insufficient balance - Export InsufficientBalanceError for error handling Completes tasks 10.1, 10.2
- Create comprehensive gas abstraction screen with all components - Add balance display with pending/available calculations - Implement top-up modal with amount selector and validation - Add transaction history with top-ups and sponsored transactions - Implement low balance warning banner - Add gasless mode toggle with persistence - Add explanatory text and refund footnote - Integrate GasAbstractionProvider into root layout - Add screen to navigation - Update top-up endpoint to handle transaction signing via Grid - Note: Transaction signing flow needs Grid SDK sign-only support (TODO) Completes tasks 11.1, 11.2, 11.3, 11.4, 11.5, 11.6
…ntegration - Add gasless mode toggle to SendModal with balance validation - Display estimated cost (USDC for gasless, SOL for regular) - Implement gasless transaction flow via /api/grid/send-tokens-gasless endpoint - Add comprehensive error handling (402, 400, 503 errors) - Create backend gasless endpoint that builds, sponsors, signs, and submits transactions - Add gaslessMode preference to clientContext for server communication - Update ChatManager to pass gasless mode preference to server - Modify useGasAbstraction hook to return null instead of throwing (allows conditional usage) - Update gas-abstraction screen to handle null context gracefully Completes tasks 12.1, 12.2, 12.3, 12.4, 13.1 Remaining: 13.2 (server-side tool transaction sponsorship), 13.3 (notifications)
- Add gaslessMode to X402Context interface - Update createGridSender to support gasless mode parameter - Implement gasless transaction flow in createGridSender with fallback to SOL - Pass gasless mode preference from clientContext to tool handlers - Add notification logging for gasless transactions with cost display - Handle gasless transaction errors gracefully with SOL fallback Completes tasks 13.2, 13.3 All tasks 12.1-12.4 and 13.1-13.3 now complete
- Rename duplicate 'result' variable to 'sendResult' in gasless send-tokens route - Add error handling to server startup callback - Add server error handler for better error reporting Fixes compilation error that prevented server from starting on port 3001.
- Create telemetry utility with wallet hashing and event logging - Add telemetry to GasAbstractionContext for sponsorship events - Add telemetry to gas-abstraction screen for top-up events - Log all required events: topup_start/success/failure, sponsor_start/success/insufficient_balance/error - Include metadata: wallet (hashed), environment, error codes, amounts Requirements: 13.3, 13.4, 13.5, 13.6, 13.7, 13.8, 13.9, 13.10, 13.12
- Add retry logic for balance fetch (transient network errors, 5xx) - Add error handling for old blockhash errors (400 with blockhash message) - Add error handling for service unavailable (503) with graceful degradation - Ensure wallet continues to work with SOL gas when gateway fails - Keep last known balance on error (graceful degradation) - Do not break core wallet functionality on gateway errors Requirements: 15.1, 15.2, 15.3, 15.4, 15.5, 15.6, 2.12, 4.18, 7.7
- Add specific error UI for insufficient balance with top-up button - Add specific error UI for service unavailable with retry and fallback - Add specific error UI for prohibited instructions with fallback - Add specific error UI for validation errors - Show balance details (current and required) for insufficient balance errors - Allow fallback to SOL fee payment for all error types - Log gas_sponsor_fallback_to_sol telemetry when user chooses SOL - Clear error state when modal opens/closes Requirements: 7.1, 7.2, 7.3, 7.5, 7.6, 7.7, 4.17, 4.19, 4.20, 13.10
- Task 13.1: Ensure gasless mode is checked and passed to backend via clientContext - Task 13.2: Backend already implements sponsorship in createGridSender (server-side) - Task 13.3: Add user notifications for gasless transactions - Monitor gas balance changes to detect sponsored transactions - Show alert when transaction is sponsored with cost in USDC - Track tool execution timing to correlate balance changes Requirements: 8.1, 8.4, 12.5, 12.6, 4.1, 4.2, 4.5, 4.6, 4.7, 4.8, 12.7, 2.5, 10.5
- Test signature generation with known keypair
- Verify message format: x402-wallet-claim:{path}:{nonce}
- Validate base58 encoding of signatures
- Test nonce uniqueness across multiple calls
- Test UUIDv4 nonce format validation
- Test signature verification with public key
- Test error handling for missing address and private key
- Test different private key formats in session secrets
- Test 32-byte seed derivation
- Test base58-encoded private key handling
- Test grid session with authentication.address
All 12 tests passing.
Requirements: 6.1, 6.2, 6.3, 6.4, 6.5, 6.6
- Mock gateway API responses for all methods - Test balance parsing and base unit conversion - Test error handling for each status code (402, 400, 401, 503) - Test authentication header generation - Test network/asset validation - Test retry logic for 401 and 5xx errors - Test top-up submission and sponsorship flows - Test error message parsing for prohibited instructions and old blockhash All 19 tests passing. Requirements: 2.1, 2.2, 3.1, 4.1, 7.1, 7.2, 7.3, 7.4, 3.3, 3.4
- Test balance state updates and available balance calculation - Test 10-second staleness check logic - Test gasless mode toggle and persistence - Test low balance detection (< 0.1 USDC threshold) - Test transaction history parsing (topups and usages) - Test pending amount calculation from usages - Test insufficient balance detection All 13 tests passing. Requirements: 2.3, 2.4, 2.6, 8.1, 9.1
- Test balance fetch from gateway via backend API - Verify authentication headers are generated and sent - Validate response parsing (balance, topups, usages) - Test 10-second cache behavior - Test error handling for missing Grid session and auth token - Tests skip gracefully when test credentials or gateway unavailable Requirements: 2.1, 2.2, 2.3, 2.6, 6.1, 6.2, 6.3, 6.4, 6.5
- Test getting payment requirements from gateway - Test network and asset validation - Test USDC transfer VersionedTransaction creation - Test x402 payment submission with publicKey field - Test balance update verification - Test error handling for missing requirements and invalid transactions - Tests skip gracefully when test credentials or gateway unavailable Requirements: 3.1, 3.2, 3.3, 3.4, 3.6, 3.10, 3.12, 3.13, 3.14, 3.15, 11.1, 11.2, 11.3
- Test creating transaction with fresh blockhash - Test requesting sponsorship for transaction - Test verifying sponsored transaction structure - Test handling insufficient balance errors (402) - Test error handling for missing transaction and Grid session - Note: Actual Solana submission and settlement verification in E2E tests Requirements: 4.1, 4.2, 4.5, 4.6, 4.7, 4.8, 5.1, 5.2, 5.3, 5.4, 5.5
- Test creating transaction with old/expired blockhash - Test 400 error for old blockhash - Test blockhash error message parsing - Test retry with fresh blockhash when old blockhash detected - Tests verify error handling and retry logic for expired blockhashes Requirements: 4.18, 15.5
- Test complete gasless transaction flow (top-up → send → verify) - Test insufficient balance handling with 402 error - Test graceful degradation when gateway unavailable - Tests verify full user journey from top-up to transaction sponsorship - Tests skip gracefully when credentials or gateway unavailable Note: Task 18.3 (failed transaction refund) requires actual Solana transaction submission and settlement monitoring, which is better suited for manual testing or dedicated test environment. Requirements: All requirements, 7.1, 9.1, 9.2, 9.3, 9.4, 4.16, 15.1, 15.2, 15.4, 7.5, 7.7
- Add JSON parsing for gridSession data in balance endpoint - Improve error handling and logging in gas abstraction routes - Enhance wallet auth generator with better error handling - Expand integration and e2e test coverage - Add debug logging for troubleshooting
- Add comprehensive API documentation with endpoints, examples, and error codes - Create user guide explaining gas credits and usage - Add deployment guide for staging and production rollout
- Add test:integration:gas and test:e2e:gas scripts to package.json - Add gas abstraction integration tests to CI workflow - Add gas abstraction E2E tests to CI workflow - Add GAS_GATEWAY_URL and SOLANA_RPC_URL to backend server env - Create changeset for gas abstraction feature (minor version bump)
![vercel[bot]](https://avatars.githubusercontent.com/in/8329?s=60&v=4){kind=small}
- Replace non-existent createX402GasAbstractionService() with direct instantiation - Add fallback values (0) for required/available balance fields to prevent NaN errors - Fixes runtime errors in gasless transaction endpoints - Prevents NaN display in insufficient balance error messages
- Add URL protocol validation for GAS_GATEWAY_URL and SOLANA_RPC_URL - Fix JSON parsing error handling to return 400 immediately on parse failures - Normalize gateway response by extracting fields from accepts array - Clean up logging and remove unused blockhash endpoint - Improve error messages for malformed authentication data
- Add RPC fallback endpoints (Alchemy) for reliable connection - Extract payTo from gateway accepts array (gateway returns nested structure) - Fix TokenOwnerOffCurveError by adding allowOwnerOffCurve for Grid PDA wallets - Add gas abstraction link to wallet screen main menu - Improve light mode styling with better contrast and borders - Enhance error handling with detailed logging and validation - Add comprehensive field extraction from gateway accepts array - Improve error messages for better debugging
5 tasks
…r x402 payments - Increase retry attempts to 15 (30s wait) for transaction confirmation - Add direct RPC call to fetch raw base64 transaction bytes - Properly reconstruct VersionedTransaction from confirmed transactions - Return 408 timeout if transaction not confirmed after retries - Fix RPC response parsing for base64-encoded transactions
- Change /api/gas-abstraction/topup to expect 'payment' field (base64-encoded) - Remove duplicate amountBaseUnits declaration - Add enhanced logging for payment payload structure - Improve error parsing for 402 and 400 responses
- Prioritize Alchemy RPC URLs from environment variables - Add allowOwnerOffCurve: true for Grid PDA wallets in getAssociatedTokenAddress - Make balance test wallet validation more flexible - All integration tests now passing (6 balance, 4 blockhash, 7 top-up, 6 sponsor)
- Prioritize Alchemy RPC URLs from environment variables - Add allowOwnerOffCurve: true for Grid PDA wallets - Handle insufficient balance error structure (required can be string or number) - All E2E tests now passing (4 tests)
- Build full x402 payment payload structure (x402Version, scheme, network, asset, payload)
- Use scheme from gateway requirements ('exact' instead of hardcoded 'solana')
- Remove hardcoded Alchemy RPC URLs, use environment variables
- Fix duplicate token variable declaration
…ns 402 despite all fixes
Contributor
Author
|
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
feat(gas): Add x402 gas abstraction feature
Overview
This PR implements the x402 gas abstraction feature, allowing users to pay Solana transaction fees using USDC credits instead of SOL. Users can pre-pay USDC to a gas gateway, and Mallory will automatically sponsor transactions using these credits when gasless mode is enabled.
Key Features
Backend
/api/gas-abstraction/*)Client
GasSponsorClientinterface for agent integrationsUser Experience
Technical Details
Architecture
GAS_ABSTRACTION_ENABLEDflag to control feature availabilityEnvironment Variables
GAS_GATEWAY_URL: Gas gateway API endpointGAS_GATEWAY_NETWORK: Solana network (default: "solana-mainnet-beta")GAS_GATEWAY_USDC_MINT: USDC mint addressSOLANA_RPC_URL: Solana RPC endpoint for blockhash refreshTesting
Test Coverage
Unit Tests:
Integration Tests:
E2E Tests:
CI Integration
test:integration:gasandtest:e2e:gasscripts topackage.jsonFiles Changed
Backend
apps/server/src/lib/walletAuthGenerator.ts- Authentication generatorapps/server/src/lib/x402GasAbstractionService.ts- Core serviceapps/server/src/lib/gasAbstractionConfig.ts- Configurationapps/server/src/lib/telemetry.ts- Telemetry loggingapps/server/src/lib/blockhashHelper.ts- Blockhash utilitiesapps/server/src/lib/gasAbstractionTopupHelper.ts- Top-up helperapps/server/src/routes/gasAbstraction.ts- API routesapps/server/src/lib/__tests__/walletAuthGenerator.test.ts- Unit testsapps/server/src/lib/__tests__/x402GasAbstractionService.test.ts- Unit testsClient
apps/client/contexts/GasAbstractionContext.tsx- React contextapps/client/lib/gasAbstraction.ts- Client utilitiesapps/client/lib/gasSponsorClient.ts- Developer APIapps/client/lib/telemetry.ts- Client telemetryapps/client/app/(main)/gas-abstraction.tsx- Gas credits screenapps/client/components/wallet/SendModal.tsx- Gasless send integrationapps/client/features/chat/ChatManager.tsx- AI tool integrationapps/client/__tests__/unit/GasAbstractionContext.test.tsx- Unit testsapps/client/__tests__/integration/gas-abstraction-*.test.ts- Integration tests (4 files)apps/client/__tests__/e2e/gas-abstraction-complete-flow.test.ts- E2E testDocumentation
Docs/x402-gas-abstraction/USER_GUIDE.md- User guideDocs/x402-gas-abstraction/API_DOCUMENTATION.md- API documentationDocs/x402-gas-abstraction/DEPLOYMENT.md- Deployment guideCI/Config
.github/workflows/test.yml- Added gas abstraction test stepsapps/client/package.json- Added test scripts.changeset/plenty-states-camp.md- Changeset for version bumpBreaking Changes
None. This is a new feature that is disabled by default via feature flag.
Migration Guide
No migration required. The feature is opt-in via the
GAS_ABSTRACTION_ENABLEDenvironment variable.Related
.kiro/specs/x402-gas-abstraction/Checklist
Note: This PR requires the following GitHub secrets to be configured for CI:
GAS_GATEWAY_URLSOLANA_RPC_URLReferences
https://gist.github.com/carlos-sqds/44bc364a8f3cedd329f3ddbbc1d00d06