dApp Integration Guide

This comprehensive guide will walk you through integrating eckoWALLET into your decentralized application step by step.

What You'll Learn

• Detecting and connecting to eckoWALLET

• Managing connection state

• Retrieving account information

• Signing transactions

• Handling user interactions

• Best practices and error handling

Prerequisites

• Basic knowledge of JavaScript/TypeScript

• Understanding of Kadena blockchain and Pact smart contracts

• A web application or dApp to integrate with

Quick Start

1. Detect eckoWALLET

First, check if eckoWALLET is installed:

const isEckoInstalled = () => {
  return typeof window !== 'undefined' &&
         window.kadena &&
         window.kadena.isKadena;
};

if (isEckoInstalled()) {
  console.log('eckoWALLET is installed!');
} else {
  console.log('Please install eckoWALLET');
}

2. Connect to Wallet

Request permission to connect:

const connectWallet = async () => {
  try {
    const result = await window.kadena.request({
      method: 'kda_connect',
      networkId: 'mainnet01'  // or 'testnet04'
    });

    if (result.status === 'success') {
      console.log('Connected!', result.account);
      return result.account;
    }
  } catch (error) {
    console.error('Connection failed:', error);
  }
};

3. Get Account Info

Retrieve connected account details:

const getAccountInfo = async () => {
  const account = await window.kadena.request({
    method: 'kda_requestAccount',
    networkId: 'mainnet01'
  });

  return account.wallet;
};

4. Sign Transaction

Request transaction signature from user:

const signTransaction = async (pactCode, caps) => {
  const result = await window.kadena.request({
    method: 'kda_requestSign',
    data: {
      networkId: 'mainnet01',
      signingCmd: {
        sender: accountAddress,
        chainId: '1',
        gasPrice: 0.000001,
        gasLimit: 2500,
        ttl: 28800,
        code: pactCode,
        caps: caps
      }
    }
  });

  return result.signedCmd;
};

Complete Integration Example

Here's a full React component demonstrating eckoWALLET integration:

import React, { useState, useEffect } from 'react';

interface WalletState {
  isInstalled: boolean;
  isConnected: boolean;
  account: string | null;
  publicKey: string | null;
  balance: number | null;
}

const WalletIntegration: React.FC = () => {
  const [wallet, setWallet] = useState<WalletState>({
    isInstalled: false,
    isConnected: false,
    account: null,
    publicKey: null,
    balance: null
  });

  // Check if eckoWALLET is installed
  useEffect(() => {
    const checkWallet = async () => {
      const isInstalled = window.kadena?.isKadena || false;
      setWallet(prev => ({ ...prev, isInstalled }));

      if (isInstalled) {
        // Check if already connected
        await checkConnection();
      }
    };

    // Wait for page load
    if (document.readyState === 'complete') {
      checkWallet();
    } else {
      window.addEventListener('load', checkWallet);
      return () => window.removeEventListener('load', checkWallet);
    }
  }, []);

  // Listen for account changes
  useEffect(() => {
    if (wallet.isInstalled) {
      window.kadena.on('res_accountChange', handleAccountChange);
      return () => {
        // Cleanup if needed
      };
    }
  }, [wallet.isInstalled]);

  const checkConnection = async () => {
    try {
      const result = await window.kadena.request({
        method: 'kda_checkStatus',
        networkId: 'mainnet01'
      });

      if (result.result.status === 'success') {
        setWallet(prev => ({
          ...prev,
          isConnected: true,
          account: result.result.account.account,
          publicKey: result.result.account.publicKey
        }));

        await fetchBalance(result.result.account.account);
      }
    } catch (error) {
      console.error('Connection check failed:', error);
    }
  };

  const handleConnect = async () => {
    try {
      const result = await window.kadena.request({
        method: 'kda_connect',
        networkId: 'mainnet01'
      });

      if (result.status === 'success') {
        setWallet(prev => ({
          ...prev,
          isConnected: true,
          account: result.account.account,
          publicKey: result.account.publicKey
        }));

        await fetchBalance(result.account.account);
      }
    } catch (error) {
      console.error('Connection failed:', error);
      alert('Failed to connect wallet');
    }
  };

  const handleDisconnect = async () => {
    try {
      await window.kadena.request({
        method: 'kda_disconnect',
        networkId: 'mainnet01',
        domain: window.location.hostname
      });

      setWallet(prev => ({
        ...prev,
        isConnected: false,
        account: null,
        publicKey: null,
        balance: null
      }));
    } catch (error) {
      console.error('Disconnect failed:', error);
    }
  };

  const handleAccountChange = async () => {
    console.log('Account changed, refreshing...');
    await checkConnection();
  };

  const fetchBalance = async (account: string) => {
    try {
      const accountInfo = await window.kadena.request({
        method: 'kda_requestAccount',
        networkId: 'mainnet01'
      });

      if (accountInfo.status === 'success') {
        setWallet(prev => ({
          ...prev,
          balance: accountInfo.wallet.balance
        }));
      }
    } catch (error) {
      console.error('Failed to fetch balance:', error);
    }
  };

  const handleSendTransaction = async () => {
    if (!wallet.account) return;

    try {
      const result = await window.kadena.request({
        method: 'kda_sendKadena',
        data: {
          networkId: 'mainnet01',
          account: 'k:recipient-public-key',
          amount: 1.0,
          chainId: '1',
          sourceChainId: '1',
          domain: window.location.hostname
        }
      });

      if (result.status === 'success') {
        alert('Transaction sent successfully!');
        await fetchBalance(wallet.account);
      }
    } catch (error) {
      console.error('Transaction failed:', error);
      alert('Transaction failed');
    }
  };

  // Render UI
  if (!wallet.isInstalled) {
    return (
      <div>
        <h2>eckoWALLET Not Found</h2>
        <p>Please install eckoWALLET to use this dApp.</p>
        <a href="https://eckowallet.com" target="_blank" rel="noopener noreferrer">
          Install eckoWALLET
        </a>
      </div>
    );
  }

  if (!wallet.isConnected) {
    return (
      <div>
        <h2>Connect Your Wallet</h2>
        <button onClick={handleConnect}>
          Connect eckoWALLET
        </button>
      </div>
    );
  }

  return (
    <div>
      <h2>Wallet Connected</h2>
      <div>
        <p><strong>Account:</strong> {wallet.account}</p>
        <p><strong>Public Key:</strong> {wallet.publicKey?.substring(0, 16)}...</p>
        <p><strong>Balance:</strong> {wallet.balance?.toFixed(4)} KDA</p>
      </div>

      <div>
        <button onClick={handleSendTransaction}>Send 1 KDA</button>
        <button onClick={handleDisconnect}>Disconnect</button>
      </div>
    </div>
  );
};

export default WalletIntegration;

Step-by-Step Integration

Step 1: Project Setup

Install necessary dependencies:

npm install @kadena/client @kadena/cryptography-utils

Or with Yarn:

yarn add @kadena/client @kadena/cryptography-utils

Step 2: Create Wallet Context (React)

Create a context to manage wallet state throughout your app:

// WalletContext.tsx
import React, { createContext, useContext, useState, useEffect } from 'react';

interface WalletContextType {
  isInstalled: boolean;
  isConnected: boolean;
  account: string | null;
  publicKey: string | null;
  connect: () => Promise<void>;
  disconnect: () => Promise<void>;
  signTransaction: (cmd: SigningCommand) => Promise<any>;
}

const WalletContext = createContext<WalletContextType | undefined>(undefined);

export const WalletProvider: React.FC = ({ children }) => {
  const [isInstalled, setIsInstalled] = useState(false);
  const [isConnected, setIsConnected] = useState(false);
  const [account, setAccount] = useState<string | null>(null);
  const [publicKey, setPublicKey] = useState<string | null>(null);

  useEffect(() => {
    // Check installation
    const checkInstallation = () => {
      const installed = window.kadena?.isKadena || false;
      setIsInstalled(installed);
    };

    if (document.readyState === 'complete') {
      checkInstallation();
    } else {
      window.addEventListener('load', checkInstallation);
    }

    // Check existing connection
    checkConnection();

    return () => window.removeEventListener('load', checkInstallation);
  }, []);

  useEffect(() => {
    if (isInstalled) {
      // Listen to account changes
      window.kadena.on('res_accountChange', handleAccountChange);
    }
  }, [isInstalled]);

  const checkConnection = async () => {
    if (!window.kadena?.isKadena) return;

    try {
      const result = await window.kadena.request({
        method: 'kda_checkStatus',
        networkId: 'mainnet01'
      });

      if (result.result?.status === 'success') {
        setIsConnected(true);
        setAccount(result.result.account.account);
        setPublicKey(result.result.account.publicKey);
      }
    } catch (error) {
      console.error('Connection check failed:', error);
    }
  };

  const connect = async () => {
    try {
      const result = await window.kadena.request({
        method: 'kda_connect',
        networkId: 'mainnet01'
      });

      if (result.status === 'success') {
        setIsConnected(true);
        setAccount(result.account.account);
        setPublicKey(result.account.publicKey);
      }
    } catch (error) {
      throw new Error('Failed to connect wallet');
    }
  };

  const disconnect = async () => {
    try {
      await window.kadena.request({
        method: 'kda_disconnect',
        networkId: 'mainnet01',
        domain: window.location.hostname
      });

      setIsConnected(false);
      setAccount(null);
      setPublicKey(null);
    } catch (error) {
      console.error('Disconnect failed:', error);
    }
  };

  const signTransaction = async (cmd: any) => {
    const result = await window.kadena.request({
      method: 'kda_requestSign',
      data: {
        networkId: 'mainnet01',
        signingCmd: cmd
      }
    });

    return result.signedCmd;
  };

  const handleAccountChange = () => {
    checkConnection();
  };

  return (
    <WalletContext.Provider value={{
      isInstalled,
      isConnected,
      account,
      publicKey,
      connect,
      disconnect,
      signTransaction
    }}>
      {children}
    </WalletContext.Provider>
  );
};

export const useWallet = () => {
  const context = useContext(WalletContext);
  if (!context) {
    throw new Error('useWallet must be used within WalletProvider');
  }
  return context;
};

Step 3: Use the Wallet Hook

// MyComponent.tsx
import { useWallet } from './WalletContext';

const MyComponent = () => {
  const { isConnected, account, connect, disconnect } = useWallet();

  return (
    <div>
      {!isConnected ? (
        <button onClick={connect}>Connect Wallet</button>
      ) : (
        <>
          <p>Connected: {account}</p>
          <button onClick={disconnect}>Disconnect</button>
        </>
      )}
    </div>
  );
};

Step 4: Signing Transactions

Create a utility function for building and signing transactions:

// transactionUtils.ts
export const buildTransferCommand = (
  sender: string,
  receiver: string,
  amount: number,
  chainId: string,
  publicKey: string
) => {
  return {
    code: `(coin.transfer "${sender}" "${receiver}" ${amount.toFixed(1)})`,
    data: {},
    sender: sender,
    chainId: chainId,
    gasPrice: 0.000001,
    gasLimit: 2500,
    ttl: 28800,
    caps: [
      {
        role: 'Gas Payer',
        description: 'Pay gas for this transaction',
        cap: {
          name: 'coin.GAS',
          args: []
        }
      },
      {
        role: 'Sender',
        description: `Transfer ${amount} KDA to ${receiver}`,
        cap: {
          name: 'coin.TRANSFER',
          args: [sender, receiver, amount]
        }
      }
    ]
  };
};

export const sendSignedTransaction = async (
  signedCmd: any,
  networkUrl: string
) => {
  const response = await fetch(`${networkUrl}/api/v1/send`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ cmds: [signedCmd] })
  });

  const result = await response.json();
  return result.requestKeys[0];  // Transaction hash
};

export const pollTransactionStatus = async (
  requestKey: string,
  networkUrl: string
) => {
  const response = await fetch(`${networkUrl}/api/v1/poll`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ requestKeys: [requestKey] })
  });

  const result = await response.json();
  return result[requestKey];
};

Usage:

const { signTransaction, account } = useWallet();

const sendKDA = async () => {
  const cmd = buildTransferCommand(
    account,
    'k:receiver-pubkey',
    1.0,
    '1',
    publicKey
  );

  // Sign with eckoWALLET
  const signedCmd = await signTransaction(cmd);

  // Send to blockchain
  const requestKey = await sendSignedTransaction(
    signedCmd,
    'https://api.chainweb.com/chainweb/0.0/mainnet01'
  );

  console.log('Transaction hash:', requestKey);

  // Poll for result
  const result = await pollTransactionStatus(
    requestKey,
    'https://api.chainweb.com/chainweb/0.0/mainnet01'
  );

  console.log('Result:', result);
};

Advanced Patterns

Multi-Chain Support

const [currentChain, setCurrentChain] = useState('1');

const switchChain = async (chainId: string) => {
  // eckoWALLET manages chain switching in the UI
  // Your dApp should react to chain changes via events
  setCurrentChain(chainId);
};

// Listen for chain changes
useEffect(() => {
  window.kadena?.on('res_getChain', (event) => {
    setCurrentChain(event.chainId);
  });
}, []);

Batch Transactions (QuickSign)

const signMultipleTransactions = async (transactions: any[]) => {
  const commandSigDatas = transactions.map(tx => ({
    cmd: JSON.stringify(tx),
    sigs: [{
      pubKey: publicKey,
      sig: null  // Request signature
    }]
  }));

  const result = await window.kadena.request({
    method: 'kda_requestQuickSign',
    data: {
      networkId: 'mainnet01',
      commandSigDatas
    }
  });

  return result.quickSignData;
};

Error Handling Best Practices

const safeWalletRequest = async (config: any) => {
  try {
    const result = await window.kadena.request(config);

    if (result.status === 'fail') {
      throw new Error(result.message || 'Request failed');
    }

    return result;

  } catch (error: any) {
    // Handle specific errors
    if (error.message?.includes('User rejected')) {
      console.log('User cancelled');
      return null;
    }

    if (error.message?.includes('locked')) {
      alert('Please unlock your eckoWALLET');
      return null;
    }

    // Generic error
    console.error('Wallet request failed:', error);
    throw error;
  }
};

Testing Your Integration

Local Testing

1. Install eckoWALLET: Add extension to your browser

2. Switch to Testnet: In eckoWALLET settings, switch to testnet04

3. Get Test KDA: Use a testnet faucet

4. Test Transactions: Try all flows in your dApp

Testing Checklist

• Wallet detection works

• Connect button functions

• Account display is correct

• Balance updates properly

• Transaction signing works

• Error handling is appropriate

• Account switching is detected

• Disconnect works correctly

• UI updates on wallet events

Common Issues and Solutions

Wallet Not Detected

Issue: window.kadena is undefined

Solutions:

• Wait for page load before checking

• Add small delay for extension injection

• Show installation prompt if not found

Connection Fails

Issue: User can't connect

Possible causes:

• Wallet is locked

• Wrong network selected

• User rejected request

Solutions:

• Check wallet is unlocked

• Verify network ID matches

• Handle rejection gracefully

Transaction Signing Fails

Issue: Signing request fails

Common causes:

• Invalid Pact code

• Incorrect capabilities

• Insufficient gas

• Wrong chain ID

Solutions:

• Validate Pact code before signing

• Ensure capabilities match code

• Use appropriate gas settings

• Verify chain ID

Best Practices

1. User Experience

• Show clear installation prompts

• Provide feedback during operations

• Handle errors gracefully

• Don't assume wallet is installed

2. Security

• Always verify transaction details with users

• Don't auto-sign without user interaction

• Validate all inputs

• Use HTTPS for your dApp

3. Performance

• Cache connection state

• Debounce frequent requests

• Lazy load wallet integration

• Minimize unnecessary requests

4. Compatibility

• Test on multiple browsers

• Handle edge cases

• Provide fallbacks

• Keep dependencies updated

Next Steps

• API Reference - Complete API documentation

• Transaction Signing - Deep dive into signing

• Code Examples - More ready-to-use examples

• Testing Your Integration - Comprehensive testing guide

Resources

• Kadena Documentation

• Pact Language

• eckoWALLET Website

Need Help?

• Join our Discord: https://discord.com/invite/runonflux

• Follow us: @eckoWALLET

• Check Troubleshooting Guide