For Developers

Events

Last updated: 7/2/2025

Event System

DropFi provides a comprehensive event system to keep your DApp synchronized with wallet state changes.

📡 Event Listeners

Subscribing to Events

javascript
window.xrpl.on(eventName: string, callback: function): void

Example:

javascript
// Listen for account changes
window.xrpl.on('xrpl_selectedAddress', (address) => {
    console.log('Active account changed to:', address);
    updateUIForAccount(address);
});

Unsubscribing from Events

javascript
window.xrpl.off(eventName: string, callback: function): void

Example:

javascript
const handler = (address) => console.log(address);

// Subscribe
window.xrpl.on('xrpl_selectedAddress', handler);

// Later: Unsubscribe
window.xrpl.off('xrpl_selectedAddress', handler);

🎯 Available Events

xrpl_selectedAddress

Fired when the active account changes.

javascript
window.xrpl.on('xrpl_selectedAddress', (address) => {
    // address: string | null
    console.log('New active address:', address);
});

Triggers:

User switches accounts
User connects wallet
User disconnects (address will be null)

xrpl_connectedAccounts

Fired when the list of connected accounts changes.

javascript
window.xrpl.on('xrpl_connectedAccounts', (accounts) => {
    // accounts: string[]
    console.log('Connected accounts:', accounts);
});

Triggers:

New account connected
Account disconnected
Initial connection

xrpl_selectedNetwork

Fired when the network changes.

javascript
window.xrpl.on('xrpl_selectedNetwork', (network) => {
    // network: string
    console.log('Network changed to:', network);
});

Triggers:

User switches network
DApp requests network change

xrpl_disconnect

Fired when the wallet disconnects.

javascript
window.xrpl.on('xrpl_disconnect', (previousAddress) => {
    // previousAddress: string
    console.log('Disconnected from:', previousAddress);
});

Triggers:

User disconnects via wallet
User revokes site permission
DApp calls disconnect()

🔄 Legacy Event Support

For compatibility with other XRPL wallets, DropFi also supports these legacy events:

accountsChanged

javascript
window.xrpl.on('accountsChanged', (accounts) => {
    // accounts: string[]
    const primaryAccount = accounts[0] || null;
    console.log('Primary account:', primaryAccount);
});

networkChanged

javascript
window.xrpl.on('networkChanged', (network) => {
    // network: {network: string, endpoint: string}
    console.log('Network:', network.network);
    console.log('Endpoint:', network.endpoint);
});

disconnect

javascript
window.xrpl.on('disconnect', (address) => {
    // address: string
    console.log('Disconnected:', address);
});

💻 Complete Event Example

javascript
class WalletManager {
    constructor() {
        this.address = null;
        this.network = null;
        this.setupEventListeners();
    }
    
    setupEventListeners() {
        // Primary events
        window.xrpl.on('xrpl_selectedAddress', this.handleAddressChange.bind(this));
        window.xrpl.on('xrpl_selectedNetwork', this.handleNetworkChange.bind(this));
        window.xrpl.on('xrpl_disconnect', this.handleDisconnect.bind(this));
        
        // Legacy support
        window.xrpl.on('accountsChanged', this.handleAccountsChanged.bind(this));
    }
    
    handleAddressChange(address) {
        this.address = address;
        this.updateUI();
        
        if (address) {
            this.loadAccountData();
        }
    }
    
    handleNetworkChange(network) {
        this.network = network;
        this.showNetworkBanner(network);
        
        // Reload data for new network
        if (this.address) {
            this.loadAccountData();
        }
    }
    
    handleDisconnect(previousAddress) {
        this.address = null;
        this.showDisconnectedState();
        this.clearAccountData();
    }
    
    handleAccountsChanged(accounts) {
        // Legacy event handler
        const newAddress = accounts[0] || null;
        if (newAddress !== this.address) {
            this.handleAddressChange(newAddress);
        }
    }
    
    cleanup() {
        // Remove all listeners when done
        window.xrpl.off('xrpl_selectedAddress', this.handleAddressChange);
        window.xrpl.off('xrpl_selectedNetwork', this.handleNetworkChange);
        window.xrpl.off('xrpl_disconnect', this.handleDisconnect);
        window.xrpl.off('accountsChanged', this.handleAccountsChanged);
    }
}

🎨 Event-Driven UI Pattern

javascript
// React example
function WalletConnection() {
    const [address, setAddress] = useState(null);
    const [network, setNetwork] = useState(null);
    
    useEffect(() => {
        // Initial state
        if (window.xrpl) {
            window.xrpl.initialize().then(state => {
                setAddress(state.selectedAddress);
                setNetwork(state.network);
            });
        }
        
        // Event listeners
        const handleAddress = (addr) => setAddress(addr);
        const handleNetwork = (net) => setNetwork(net);
        
        window.xrpl?.on('xrpl_selectedAddress', handleAddress);
        window.xrpl?.on('xrpl_selectedNetwork', handleNetwork);
        
        // Cleanup
        return () => {
            window.xrpl?.off('xrpl_selectedAddress', handleAddress);
            window.xrpl?.off('xrpl_selectedNetwork', handleNetwork);
        };
    }, []);
    
    return (
        <div>
            {address ? (
                <div>
                    Connected: {address.slice(0, 6)}...{address.slice(-4)}
                    <br />
                    Network: {network}
                </div>
            ) : (
                <button onClick={() => window.xrpl.connect()}>
                    Connect Wallet
                </button>
            )}
        </div>
    );
}

⚡ Performance Tips

Remove unused listeners to prevent memory leaks
Debounce rapid events if needed
Cache event data to avoid redundant updates
Use specific events (xrpl_*) over legacy when possible

🔧 Debug Tip: Use console.log in event handlers during development to understand the exact timing and data of events. Remove in production!