Wallet Interaction Standards (EIPs) for dApp Developers

Back to Standards
Ergo Improvement Proposals (EIPs) define standards for interaction between dApps and wallets. See the full list at Ergo EIPs repository.

This page highlights key EIPs and expected behaviors relevant to dApp development, focusing primarily on EIP-0012 (dApp Connector). For full details, refer to the official EIP specifications.

Supported Wallets (EIP-0012)

Note: Yoroi Wallet's Ergo support is deprecated. Use Nautilus or the official Ergo Mobile Wallet for dApp interactions. See the main Wallets page for more options.

EIP-0012: dApp Connector Overview

EIP-0012 defines a standard JavaScript interface injected into the dApp's web context by the wallet (usually as window.ergoConnector.ergo or just window.ergo after connection). It separates functions into two main categories:

  • Connection API: Functions for establishing and managing the connection between the dApp and the wallet (e.g., connect, disconnect, check, isConnected).
  • Context API: Functions available after a connection is established, allowing the dApp to interact with the wallet's context (e.g., get addresses, balances, request signing).

Typical Connection Flow (Conceptual JS)

async function connectWallet() {
  // Check if the connector object exists (wallet extension installed)
  if (typeof ergoConnector === 'undefined' || !ergoConnector.ergo) {
    console.error("Ergo Wallet Connector not found. Please install Nautilus or use a compatible wallet.");
    // Optionally prompt user to install
    return null;
  }

  try {
    // Check if already connected
    const isConnected = await ergoConnector.ergo.isConnected();
    if (isConnected) {
      console.log("Wallet already connected.");
      return ergo; // Return the existing context API object
    }

    // Request read access (prompts user in wallet)
    const granted = await ergoConnector.ergo.connect(); 
    
    if (!granted) {
      console.log("Wallet connection request denied by user.");
      return null;
    } else {
      console.log("Wallet connected successfully!");
      // 'ergo' object (Context API) is now available globally or via ergoConnector.ergo
      // You might want to store this 'ergo' object reference in your dApp's state
      return ergo; 
    }
  } catch (error) {
    console.error("Error connecting to wallet:", error);
    // Handle specific errors (e.g., user cancellation, timeouts)
    return null;
  }
}

// Usage:
// const ergoContext = await connectWallet();
// if (ergoContext) {
//   // Now use ergoContext.get_used_addresses(), ergoContext.sign_tx(), etc.
// }

Connection API Functions (Examples)

  • ergoConnector.ergo.connect(): Initiates the connection request. Returns true if access granted, false otherwise.
  • ergoConnector.ergo.disconnect(): Disconnects the dApp (if supported by the wallet).
  • ergoConnector.ergo.isConnected(): Checks if the dApp currently has read access without prompting the user.

Context API Functions (ergo.*) & Expected Behavior

  • ergo.get_used_addresses(paging?): Returns addresses involved in past transactions. MUST return [] (empty array) if no addresses have been used. Supports pagination. Catch potential errors.
  • ergo.get_unused_addresses(): Returns addresses generated but not yet seen on-chain. Catch potential errors.
  • ergo.get_balance(token_id?): Returns confirmed and unconfirmed balance for ERG or a specific token. Catch potential errors.
  • ergo.sign_tx(unsignedTx): Sends an unsigned transaction to the wallet for the user to review and sign. Returns the signed transaction if approved. Handle user rejection, insufficient funds, malformed transaction errors.
  • ergo.submit_tx(signedTx): Sends a signed transaction to the wallet for submission to the network. Returns the transaction ID. Handle network/node errors.

Refer to the full EIP-0012 specification for exact function signatures, parameter/return types, and detailed error codes.

Security Best Practices

  • Request Minimal Permissions: Only request read access initially (connect).
  • User Intent: Ensure all signing requests (sign_tx) clearly correspond to an explicit user action within your dApp.
  • Transaction Clarity: Display key transaction details to the user before sending to the wallet for signing.
  • Input Validation: Sanitize and validate any user input used in transaction construction.
  • State Management: Securely manage the connection state within your dApp. Verify isConnected() before Context API calls.
  • Avoid Storing Sensitive Data: Never ask for or store user private keys or seed phrases in your dApp.

Mobile Considerations

  • Connection Initiation: The method for initiating a connection might differ on mobile (deeplinking, in-app browser, etc.).
  • User Experience: Ensure your dApp's UI is responsive and works well on mobile screens when interacting with the wallet interface.

Testing Recommendations

  • Multiple Wallets: Test your dApp integration with all supported wallets on different platforms.
  • Testnet: Thoroughly test all connection flows, data fetching, and transaction signing/submission scenarios on the Ergo Testnet before deploying to Mainnet.
  • Edge Cases: Test user cancellation flows, network errors, insufficient funds, and handling of empty/new wallets.
  • Wallet State Changes: Test how your dApp handles the user switching accounts or disconnecting the wallet while the dApp is active.

Troubleshooting Common Issues

  • ergoConnector Undefined: Wallet extension is not installed or not injecting the connector object. Prompt user to install/enable.
  • Connection Rejected: User denied the connection request. Handle gracefully.
  • sign_tx Errors: User rejected the signature, insufficient funds, malformed transaction. Handle and display errors.
  • submit_tx Errors: Network issues, node errors, or wallet unable to connect to its node. Provide feedback to the user.
  • Incorrect Data (get_used_addresses, get_balance): Ensure the wallet is fully synced. Check for pagination issues.

Other Relevant EIPs

Example Implementations

(Placeholder: Link to well-known open-source dApps or libraries demonstrating good EIP-0012 integration, e.g., Spectrum UI, Nautilus examples, Fleet examples, if available).

By understanding and correctly implementing these standards, particularly EIP-0012, dApps can provide a smoother, more secure, and reliable interaction experience across different Ergo wallets.