Skip to content

OFFRAMP_TOKEN_TRANSFER_FIX.md

Latest commit

 

History

History
152 lines (111 loc) · 6.07 KB

OFFRAMP_TOKEN_TRANSFER_FIX.md

File metadata and controls

152 lines (111 loc) · 6.07 KB
Raw

Offramp Token Transfer Fix

Problem Description

Users were seeing "Transaction Successful" messages during offramp transactions, but their tokens were not actually being deducted from their Crossmint wallets. This created a confusing user experience where the system appeared to work but no actual token transfer occurred.

Root Cause Analysis

The issue was in the Crossmint external wallet signer implementation. When using external wallet signers, Crossmint API works in a two-step process:

  1. Create Transaction: POST to /transfers endpoint returns status: "awaiting-approval" with a message to sign
  2. Submit Approval: Sign the message and POST to /approvals endpoint to complete the transaction

Our implementation was only performing step 1 and treating the "awaiting-approval" status as an error, but still returning success to the user because the transaction was created successfully.

Solution Implemented

1. Auto-Approval System

Updated CrossmintService.executeTransferWithIdempotency() to automatically handle the approval process:

  • Detect when transaction status is "awaiting-approval"
  • Automatically sign the approval message using the appropriate private key
  • Submit the approval to complete the transaction
  • Return success only after the transaction is fully approved

2. Multi-Chain Signing Support

Implemented support for both EVM and Solana chains with different signing methods:

EVM Chains (BSC, Base, Arbitrum, etc.):

  • Uses viem library for message signing
  • Messages are in hex format
  • Private key format: 0x... (hex)

Solana Chain:

  • Uses @solana/web3.js + tweetnacl for message signing
  • Messages are in base64 format
  • Private key format: base58 encoded

3. Environment Configuration

Added new environment variables for private keys:

# EVM private key (hex format) - corresponds to CROSSMINT_ADMIN_EVM_ADDRESS
CROSSMINT_ADMIN_EVM_PRIVATE_KEY=0x1234567890abcdef...

# Solana private key (base58 format) - corresponds to CROSSMINT_ADMIN_SOLANA_ADDRESS  
CROSSMINT_ADMIN_SOLANA_PRIVATE_KEY=5J1F7GHaLrWmEqhrdcGjy3QSuK2w1QGdCdqMQ3CqW2mBvXcRtgHvW8...

4. Enhanced Error Handling

  • Proper validation of private key configuration
  • Address verification to ensure private keys match signer addresses
  • Detailed logging for debugging transaction approval process
  • Graceful fallback with clear error messages

Files Modified

1. services/CrossmintService.ts

  • Updated executeTransferWithIdempotency() to handle auto-approval
  • Added submitTransactionApproval() method
  • Added signEvmMessage() and signSolanaMessage() methods
  • Added isSolanaAddress() helper method
  • Added private key getters

2. package.json

  • Added viem: ^2.21.53 for EVM message signing
  • Added @solana/web3.js: ^1.95.4 for Solana keypair management
  • Added tweetnacl: ^1.0.3 for Solana message signing
  • Added bs58: ^1.3.3 for base58 encoding/decoding

3. .env.example

  • Added CROSSMINT_ADMIN_EVM_PRIVATE_KEY configuration
  • Added CROSSMINT_ADMIN_SOLANA_PRIVATE_KEY configuration
  • Updated documentation for private key requirements

Transaction Flow (After Fix)

  1. User submits offramp transaction with PIN
  2. System validates PIN and wallet balances
  3. crossmintService.transferTokens() is called
  4. Crossmint API creates transaction with status: "awaiting-approval"
  5. NEW: System automatically signs the approval message
  6. NEW: System submits the approval to complete the transaction
  7. Transaction is fully executed and tokens are deducted
  8. User sees "Transaction Successful" only after actual completion
  9. Background process handles DexPay quote and bank transfer

Testing Requirements

1. Environment Setup

  • Configure valid private keys for both EVM and Solana admin addresses
  • Ensure private keys correspond to the configured admin addresses
  • Test with both staging and production Crossmint environments

2. Test Cases

  • EVM Token Transfer: Test USDC/USDT transfers on BSC, Base, Arbitrum
  • Solana Token Transfer: Test USDC/USDT transfers on Solana
  • Error Handling: Test with invalid private keys, mismatched addresses
  • Balance Verification: Confirm tokens are actually deducted after success message

3. Monitoring

  • Monitor transaction approval success rates
  • Track any approval failures in logs
  • Verify blockchain confirmations for completed transfers

Security Considerations

1. Private Key Management

  • Private keys must be securely stored and never logged
  • Use environment variables or secure key management systems
  • Rotate keys periodically following security best practices

2. Address Verification

  • System validates that private keys match configured admin addresses
  • Prevents accidental use of wrong private keys
  • Logs address mismatches for security monitoring

3. Transaction Validation

  • Idempotency keys prevent duplicate transactions
  • Amount and recipient validation before signing
  • Comprehensive error logging without exposing sensitive data

Deployment Checklist

  • Install new dependencies: npm install viem @solana/web3.js tweetnacl bs58
  • Configure CROSSMINT_ADMIN_EVM_PRIVATE_KEY environment variable
  • Configure CROSSMINT_ADMIN_SOLANA_PRIVATE_KEY environment variable
  • Verify private keys match admin addresses
  • Test token transfers on staging environment
  • Monitor transaction approval success rates
  • Verify actual token deductions in user wallets

Rollback Plan

If issues occur, the system can be rolled back by:

  1. Reverting to previous CrossmintService implementation
  2. Removing auto-approval logic (transactions will fail but won't show false success)
  3. Implementing manual approval process as temporary measure
  4. Investigating and fixing any configuration issues

Future Improvements

  1. Webhook Integration: Listen for Crossmint transaction status updates
  2. Retry Logic: Implement retry mechanism for failed approvals
  3. Multi-Signature Support: Support for multi-sig admin wallets
  4. Transaction Monitoring: Real-time monitoring of transaction status
  5. Key Rotation: Automated private key rotation system