Fee Delegation Setup

Fee delegation allows your dApp to sponsor transaction fees for users, removing the barrier of requiring VTHO tokens.

What is Fee Delegation?

Fee delegation is a VeChain feature that enables applications to pay transaction fees on behalf of users. This creates a seamless user experience, especially for:

New users without VTHO tokens
Social login users (email, Google, etc.)
Improving overall user onboarding

Configuration

Add fee delegation to your VeChainKitProvider:

<VeChainKitProvider
  feeDelegation={{
    delegatorUrl: "YOUR_FEE_DELEGATION_URL",
    delegateAllTransactions: true, // or false for social login only
  }}
>
  {children}
</VeChainKitProvider>

Configuration Options

delegatorUrl: The endpoint URL for your fee delegation service
delegateAllTransactions:
- true: Sponsor all transactions (wallet and social users)
- false: Sponsor only social login transactions (mandatory)

Setup Options

You have two options for setting up fee delegation:

Option 1: Create your own backend service

Option 2: Use existing free tools

Create Your Own Service

Deploy a custom fee delegation service as a microservice or backend endpoint.

Example Implementation (Cloudflare Worker)

import { 
  Address, 
  HDKey, 
  Transaction, 
  Secp256k1, 
  Hex 
} from '@vechain/sdk-core';

// Default signer for development (use env variable in production)
const DEFAULT_SIGNER = 'denial kitchen pet squirrel other broom bar gas better priority spoil cross';

export async function onRequestPost({ request, env }): Promise<Response> {
  try {
    const body = await request.json();
    console.log('Incoming fee delegation request:', body);

    // Load signer wallet from mnemonic
    const mnemonic = (env.SIGNER_MNEMONIC ?? DEFAULT_SIGNER).split(' ');
    const signerWallet = HDKey.fromMnemonic(
      mnemonic, 
      HDKey.VET_DERIVATION_PATH
    ).deriveChild(0);
    
    if (!signerWallet.publicKey || !signerWallet.privateKey) {
      throw new Error('Could not load signing wallet');
    }

    // Get signer address
    const signerAddress = Address.ofPublicKey(signerWallet.publicKey);
    
    // Decode and sign the transaction
    const transactionToSign = Transaction.decode(
      Buffer.from(body.raw.slice(2), 'hex'),
      false
    );
    
    const transactionHash = transactionToSign.getSignatureHash(
      Address.of(body.origin)
    );
    
    const signature = Secp256k1.sign(
      transactionHash.bytes, 
      signerWallet.privateKey
    );

    return new Response(JSON.stringify({
      signature: Hex.of(signature).toString(),
      address: signerAddress.toString()
    }), {
      status: 200,
      headers: {
        'Content-Type': 'application/json',
        'Access-Control-Allow-Origin': '*'
      }
    });
  } catch (error) {
    console.error('Fee delegation error:', error);
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: {
        'Content-Type': 'application/json',
        'Access-Control-Allow-Origin': '*'
      }
    });
  }
}

Environment Variables

# .env
SIGNER_MNEMONIC="your twelve word mnemonic phrase here"

Security Considerations

Never expose your mnemonic: Store it securely in environment variables
Implement request validation: Check origin, transaction limits, etc.
Add rate limiting: Prevent abuse of your delegation service
Monitor usage: Track delegation requests and VTHO consumption

Use VeChain.Energy

VeChain.Energy provides a managed fee delegation service.

Setup Steps

For a detailed walkthrough, see the VeChain.Energy Fee Delegation Tutorial.

Visit VeChain.Energy
- Go to vechain.energy
- Create an account and project
Configure Fee Delegation
- Navigate to: Your Project → Fee Delegation → Configurations
- Add the VeChain Kit smart contract address:
  - Mainnet: 0xD7B96cAC488fEE053daAf8dF74f306bBc237D3f5
  - Testnet: 0x7C5114ef27a721Df187b32e4eD983BaB813B81Cb
Get Your Delegation URL
- Your delegation URL will be: https://sponsor-testnet.vechain.energy/by/YOUR_PROJECT_ID

Configure Your Provider

<VeChainKitProvider
  feeDelegation={{
    delegatorUrl: "https://sponsor-testnet.vechain.energy/by/YOUR_PROJECT_ID",
    delegateAllTransactions: false,
  }}
>
  {children}
</VeChainKitProvider>

Smart Contract for Custom Rules

For advanced delegation rules, deploy a smart contract:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

contract FeeDelegation {
    address public owner;
    mapping(address => bool) public whitelist;
    uint256 public dailyLimit = 1000; // VTHO limit
    mapping(address => uint256) public dailyUsage;
    mapping(address => uint256) public lastUsageDate;
    
    constructor() {
        owner = msg.sender;
    }
    
    modifier onlyOwner() {
        require(msg.sender == owner, "Only owner");
        _;
    }
    
    function addToWhitelist(address user) external onlyOwner {
        whitelist[user] = true;
    }
    
    function removeFromWhitelist(address user) external onlyOwner {
        whitelist[user] = false;
    }
    
    /**
     * @dev Check if a transaction can be sponsored
     */
    function canSponsorTransactionFor(
        address _origin,
        address _to,
        bytes calldata _data
    ) public view returns (bool) {
        // Always sponsor for whitelisted addresses
        if (whitelist[_origin]) {
            return true;
        }
        
        // Check daily limit for others
        uint256 today = block.timestamp / 86400;
        if (lastUsageDate[_origin] < today) {
            return true; // New day, can sponsor
        }
        
        return dailyUsage[_origin] < dailyLimit;
    }
    
    function updateUsage(address user, uint256 amount) external {
        uint256 today = block.timestamp / 86400;
        if (lastUsageDate[user] < today) {
            dailyUsage[user] = amount;
            lastUsageDate[user] = today;
        } else {
            dailyUsage[user] += amount;
        }
    }
}

Monitoring and Alerts

For VeChain.Energy

Enable email notifications for low VTHO balance
Set up alerts in your project dashboard
Monitor usage statistics regularly

For Custom Solutions

Implement monitoring for:

VTHO balance of delegation wallet
Number of delegated transactions
Failed delegation attempts
Unusual activity patterns

// Example monitoring middleware
async function monitorDelegation(request, response, next) {
  const vthoBalance = await getVTHOBalance(DELEGATION_ADDRESS);
  
  if (vthoBalance < MINIMUM_THRESHOLD) {
    await sendAlert('Low VTHO balance for fee delegation');
  }
  
  // Log delegation request
  await logDelegationRequest({
    origin: request.body.origin,
    timestamp: Date.now(),
    transactionHash: request.body.hash
  });
  
  next();
}

Testing Fee Delegation

Test with Social Login

// Ensure social login users can transact without VTHO
const { sendTransaction } = useWallet();

try {
  const tx = await sendTransaction({
    to: '0x...',
    value: '0',
    data: '0x...'
  });
  console.log('Transaction sponsored:', tx);
} catch (error) {
  console.error('Delegation failed:', error);
}

Verify Delegation Headers. Check that your delegation service returns proper headers:
```
{
  "signature": "0x...",
  "address": "0x..."
}
```

Troubleshooting

Common Issues

"Fee delegation failed" error
- Check delegation URL is correct
- Verify VTHO balance in delegation wallet
- Ensure CORS headers are properly set
Social login users can't transact
- Confirm feeDelegation is configured in provider
- Check delegation service is running
- Verify smart contract address is whitelisted
High VTHO consumption
- Implement transaction limits
- Add user verification
- Monitor for unusual patterns

Best Practices

Security First
- Never expose private keys or mnemonics
- Implement proper authentication
- Add rate limiting
User Experience
- Ensure sufficient VTHO balance
- Provide clear error messages
- Monitor service uptime
Cost Management
- Set reasonable limits
- Track usage per user
- Implement fair use policies

PreviousGeneric Delegator - Default Option NextEmbedded Wallets

Last updated 11 days ago

Was this helpful?