What is Redelegation?
Redelegation is the process of updating an existing wallet delegation with new parameters. This replaces the previous delegation for that wallet address with a new one.Redelegation follows the exact same 3-step process as initial delegation. The new delegation completely replaces the previous one for the same wallet address.
When to Redelegate
1. Allowance Adjustment
Scenario: User needs to increase or decrease spending limit- Increase Allowance
- Decrease Allowance
- Reset Allowance
When: User’s current allowance is running low or depletedExample:
- Current allowance: 5,000 USDC
- Remaining: 500 USDC
- Want to increase to: 10,000 USDC
2. Contract Upgrades
Scenario: Platform upgrades smart contracts with new features or security improvements When It Happens:- Platform deploys new smart contract versions
- Security patches or improvements implemented
- New features added to delegation contracts
- Network-specific contract updates
- Monitor platform notifications for upgrade announcements
- Inform users of the upgrade and its benefits
- Guide users through redelegation process
- Set reasonable deadline for migration
- Provide fallback for users who don’t migrate promptly
3. Network Migration
Scenario: User wants to move delegation to a different blockchain Example Use Cases:- Switch from Ethereum to Linea for lower gas fees
- Move from Linea to Solana for faster transactions
- Consolidate multiple network wallets to single network
- Delegate new wallet on target network
- Update priority to prefer new network
- Optionally revoke old delegation (by setting allowance to 0)
4. Wallet Address Change
Scenario: User wants to use a different wallet address for the same network Common Reasons:- Upgraded to hardware wallet
- Changed wallet provider
- Security concerns with old wallet
- Using different wallet for organizational reasons
- Delegate new wallet address
- Verify new wallet works
- Remove or deprioritize old wallet
You can have multiple wallets on the same network with different addresses. Use priority to control which is used first.
5. Security Events
Scenario: Wallet potentially compromised or security best practices When to Redelegate Immediately:- Private key exposure suspected
- Wallet used on untrusted device
- Suspicious transaction activity
- Periodic security rotation (best practice)
1
Revoke Current Delegation
Set allowance to 0 on potentially compromised wallet using user’s wallet interface (not API)
2
Delegate New Wallet
Complete delegation flow with new, secure wallet
3
Verify Security
Ensure old wallet has zero allowance and new wallet is functioning
4
Monitor
Watch for any unauthorized transactions on old wallet
Redelegation Process
Redelegation uses the exact same 3-step workflow as initial delegation:Step-by-Step Redelegation
1
Request New Delegation Token
Call
GET /v1/delegation/token to generate a new single-use token2
Frontend Wallet Interaction
User approves new blockchain transaction with updated parameters:
- Same wallet address (for allowance update)
- New spending limit (if changing allowance)
- New spender address (if contract upgraded)
3
Submit New Proof
Submit proof with new transaction data using
POST /v1/delegation/evm/post-approval for EVM or POST /v1/delegation/solana/post-approval for Solana4
Verify Update
Call
GET /v1/wallet/external to confirm new allowance is reflectedImplementation Examples
Increase Allowance
Contract Upgrade Migration
Batch Redelegation
For users with multiple wallets needing updates:UI/UX Considerations
Informing Users About Redelegation
- Allowance Warning
- Contract Upgrade Notice
- Redelegation Flow
Prompt users when allowance is running low:
Best Practices
Proactive Redelegation
Monitor Allowance Usage
Monitor Allowance Usage
Set up automated monitoring to alert users before allowance runs out:
Scheduled Contract Checks
Scheduled Contract Checks
Regularly check for contract upgrades:
User Education
User Education
Educate users about when and why to redelegate:
- Include redelegation info in onboarding
- Provide in-app tooltips and guides
- Send periodic reminders about allowance status
- Explain benefits of proactive management
Graceful Degradation
Graceful Degradation
Handle scenarios where redelegation hasn’t occurred:
- Maintain multiple wallet support for failover
- Prompt users at checkout if allowance insufficient
- Provide clear error messages with actionable steps
- Allow alternative payment methods during migration periods
Testing Redelegation
Always test redelegation flows before production:Troubleshooting
Redelegation Not Reflecting New Allowance
Redelegation Not Reflecting New Allowance
Symptom: API shows old allowance after redelegationCauses:
- Blockchain transaction not confirmed
- Wrong transaction hash submitted
- Cached data in API
- Wait for blockchain confirmation (check block explorer)
- Verify transaction hash is correct
- Retry fetching wallet data after 30 seconds
User Can't Complete Redelegation
User Can't Complete Redelegation
Symptom: Transaction fails during Step 2Causes:
- Insufficient gas/SOL for transaction
- Wrong network selected in wallet
- Wallet connection lost
- Ensure user has gas funds (ETH/SOL)
- Verify correct network selected
- Reconnect wallet and retry
Contract Upgrade Breaking Changes
Contract Upgrade Breaking Changes
Symptom: Old delegation still working after supposed upgradeCauses:
- Upgrade not yet effective
- Gradual rollout in progress
- Network-specific timing
- Check upgrade effective date
- Contact platform support for rollout status
- Complete redelegation proactively regardless
Monitoring & Analytics
Track redelegation metrics for your application:Next Steps
Implementation Guide
Complete delegation workflow (applies to redelegation)
Priority Management
Manage wallet charging priority
EVM Chains
EVM-specific delegation details
Solana
Solana-specific delegation details