Welcome to the XRP Ledger Snap for MetaMask

The XRP Ledger Snap for MetaMask is an innovative extension designed to seamlessly integrate the XRP Ledger (XRPL) into your MetaMask wallet. With this Snap, you can manage XRP and other tokens on the XRPL, perform transactions, and interact with XRPL-based decentralized applications (DApps) directly from the familiar MetaMask interface. This extension enhances your cryptocurrency experience by bringing the power of the XRP Ledger to the widely-used MetaMask ecosystem.

Explore the Documentation

Getting started

This section will guide you through the initial steps to get the XRP Ledger Snap up and running. You'll find everything you need to know about installing the extension and quickly getting started with managing XRP and interacting with the XRPL.

Basics

In this section, you will explore the core features of the XRP Ledger Snap. From understanding how to use the Snap within MetaMask to securing your assets on the XRPL, this guide covers all the essential information you need to get the most out of the XRP Ledger Snap.

Development

For developers, this section provides a comprehensive guide to integrating and working with the XRP Ledger Snap. Whether you're building DApps on the XRPL or enhancing your existing applications with XRP support, you'll find detailed documentation, API references, and examples to assist you.

Support

If you encounter any issues or have questions about using the XRP Ledger Snap, this section is here to help. It provides resources and contact information for obtaining support, ensuring you can resolve any problems quickly and continue using the Snap effectively.

It’s crucial to back up your account to ensure that you don’t lose access to your funds in case of device loss or malfunction.

The XRP Ledger Snap provides two primary options for backing up your account:

1. Storing the Mnemonic of your MetaMask

The first method is to securely store the mnemonic (seed phrase) of your MetaMask wallet. This mnemonic is a 12 or 24-word phrase generated when you first set up MetaMask, and it’s the key to accessing all accounts within your MetaMask wallet, including those managed by the XRP Ledger Snap.

• Access Your Mnemonic:

  • Open MetaMask and navigate to the "Settings" section.

  • Select "Security & Privacy" and choose the option to reveal your seed phrase.

• Store It Securely

• Now you can use your mnemonic to import your account into other wallets

2. Exporting the Private Key from the XRP Ledger Snap

The second method involves exporting the private key for your XRP Ledger account directly from the XRP Ledger Snap. This key is specific to the XRP Ledger and can be used to recover your account in another wallet that supports the XRP Ledger.

• Export the Private Key:

  • Within the XRP Ledger Snap, go to account details and click export private key.

  • Choose the option to export your private key.

• Store It Securely

Learn More About Security

For more detailed information on how your funds are kept safe, visit the Security section of the documentation.

Authentication

To start using the XRP Ledger Snap, you must first authenticate with your MetaMask wallet. Upon selecting the XRPL Snap, MetaMask will prompt you to authenticate. Approve the connection request to start using the Snap with your XRP Ledger account.

Getting Your Account's Information

Once authenticated, you can easily access detailed information about your XRP Ledger account:

1. Access account information: Click into the info icon in the sidebar. Then click into the account details option and a modal with your account's information will be shown.

1. View balance and transactions: Here, you can view your XRP balance, any issued tokens, and your transaction history.

Signing transactions

The XRP Ledger Snap allows you to securely sign transactions directly within MetaMask:

1. Initiate a Transaction: Start by creating a transaction either within the Snap interface or on a DApp that supports the XRP Ledger.

2. Review Transaction Details: MetaMask will display the transaction details. Carefully review the recipient address, amount, and any associated fees.

3. Sign the Transaction: Once you’ve verified the transaction details, click on the "Sign" button. MetaMask will prompt you to confirm the action. After confirmation, the transaction will be signed using your XRP Ledger private key stored within the Snap.

4. Broadcast the Transaction: After signing, the transaction will be broadcast to the XRP Ledger network. You can track its status in the transaction history section.

Connect to multiple networks

The XRP Ledger Snap supports connecting to multiple networks.

Switch Networks Within the Snap settings, you can switch between different XRP Ledger networks, such as the mainnet, testnet, or devnet.

Export your account

To use the same XRP Ledger account in both the XRP Ledger Snap and the Xaman App, you need to import your account’s mnemonic into Xaman.

Follow these steps to seamlessly integrate your account:

Steps to Import Your Account:

1. Open the Xaman App:

   • Launch the Xaman App on your device.

2. Navigate to Settings:

   • In the Xaman App, go to the "Settings" section.

3. Access Account Management:

   • Within Settings, find the "Account" option and select it.

1. Add Account:

• In the Account section, choose "Add Account" to start the process of importing a new account.

1. Import with Mnemonic:

• Select the option to "Import with Mnemonic."

• Enter the mnemonic phrase associated with your MetaMask wallet (the same one you use with the XRP Ledger Snap).

• Complete the import process by following the on-screen prompts.

1. Verify you have MetaMask installed.

• Make sure you have the MetaMask extension installed in your browser.

2. Visit the XRPL Snap setup page.

3. Connect with MetaMask and follow the installation prompts.

1. Click into the connect button

1. Follow the installation prompts

4. Verify the installation.

After installation, verify that your XRP Ledger address is being generated correctly within MetaMask.

What are MetaMask Snaps

MetaMask Snaps are modular extensions that allow developers to expand the functionality of the MetaMask wallet. Snaps are built using MetaMask’s Snaps API, enabling developers to introduce new protocols, blockchains, or features into the MetaMask ecosystem without needing to modify the core MetaMask software. This extensibility empowers users to interact with a wider range of decentralized networks and applications directly from their MetaMask wallet.

What can you do with the XRP Ledger Snap

The XRP Ledger Snap allows users to seamlessly interact with the XRP Ledger (XRPL) through their MetaMask wallet. By installing this Snap, users can manage XRP and other tokens on the XRPL, perform transactions, and engage with XRPL-based decentralized applications (DApps) without leaving the MetaMask interface. The Snap bridges the gap between MetaMask and the XRP Ledger, bringing the speed and efficiency of the XRPL to a widely-used Ethereum wallet.

How to use the XRP Ledger Snap

1. Using the Official Snap Page:

1. Using Other DApps:

• The XRP Ledger Snap is also compatible with other decentralized applications (DApps) that are built on or interact with the XRP Ledger.

• When you visit a compatible DApp, your MetaMask wallet (with the XRP Ledger Snap installed) will automatically recognize the application, allowing you to perform transactions and manage your assets seamlessly.

• This feature makes it easy to use your MetaMask wallet across various platforms that support the XRP Ledger, providing a unified and consistent user experience.

Features Overview

• XRP Management: Manage your XRP balance directly within MetaMask. View your balance, send and receive XRP, and keep track of your transactions on the XRP Ledger.

• Token and NFT Support: In addition to XRP, the Snap supports other tokens and NFTs issued on the XRP Ledger, enabling you to manage a diverse portfolio of assets within MetaMask.

• Transaction Management: Easily perform and manage transactions on the XRP Ledger. The Snap provides a user-friendly interface for sending and receiving payments and interacting with smart contracts.

• DApp Integration: The XRP Ledger Snap integrates with decentralized applications (DApps) built on the XRP Ledger, allowing you to interact with these applications directly through MetaMask.

• Security and Privacy: The Snap leverages MetaMask’s security model while adding support for the XRP Ledger, ensuring that your assets and data remain secure.

• Seamless Experience: The XRP Ledger Snap is designed to provide a seamless user experience, bringing the functionality of the XRP Ledger into the familiar MetaMask interface with minimal setup required.

System Requirements:

• A modern browser (e.g., Chrome, Firefox) with the MetaMask extension installed.

• Internet connection to download and install the XRP Ledger Snap.

Step-by-Step Installation:

1. Install MetaMask:
2. Update MetaMask:

   • Ensure your MetaMask extension is up-to-date to avoid compatibility issues. You can check for updates in your browser’s extension settings.

3. Access the Snaps Section:

   • Open MetaMask, navigate to the settings, and find the "Snaps" section. This is where you’ll manage and install Snaps like the XRPL Snap.

4. Add the XRP Ledger Snap:

   • You can add the XRP Ledger Snap by entering the Snap’s URL into the Snaps section or by finding it in the Snap store.

5. Follow the Installation Prompts:

   • MetaMask will guide you through the installation process. Follow the on-screen instructions to complete the setup.

6. Grant Permissions:

   • During installation, you’ll be prompted to grant the XRP Ledger Snap access to certain features. Review these permissions carefully before accepting them.

7. Final Setup:

   • Once installed, the XRP Ledger Snap will appear in your Snaps section. Click on it to ensure it’s enabled and ready for use.

To use the same XRP Ledger account in both the XRP Ledger Snap and the Crossmark App, you can import your account using either the private key or the mnemonic phrase associated with your MetaMask wallet. Here’s a step-by-step guide on how to do this:

Steps to Import Your Account:

1. Open the Crossmark App:

• Launch the Crossmark App on your device.

2. Navigate to Account Management:

• Tap the Menu icon in the bottom right corner.

• Select MORE.

• Select ADD Card.

3. Add a New Account:

• Choose Import Existing to bring in an existing account.

4. Choose Import Method:

• You’ll be prompted to select your preferred import method.

• To Import with Private Key:

  • Select Private Key as the import type.

  • Enter your private key in the provided field.

  • Tap Proceed to complete the import.

• To Import with Mnemonic:

  • Select Mnemonic Phrase as the import type.

  • Enter the mnemonic phrase associated with your MetaMask wallet (the same one you use with the XRP Ledger Snap).

  • Tap Proceed and follow the on-screen prompts to complete the import process.

5. Final Steps:

• After importing, verify that your XRP Ledger account has been correctly added to Crossmark.

• You can now use the same account in both the XRPL Snap within MetaMask and the Crossmark App.

This section will guide you through interacting with the XRP Ledger using the XRP Ledger Snap. You'll learn how to request account balances, submit transactions, make payments, create trustlines, and send tokens.

Before using the XRP Ledger Snap you must read first the official documentation of the XRPL.

Getting account information

Getting Account Balance

To retrieve the balance of an XRP Ledger account, you can use the following method:

const res = await provider.request({
  method: 'wallet_invokeSnap',
  params: {
    snapId: 'npm:xrpl-snap',
    request: {
      method: 'xrpl_request',
      params: {
        command: 'account_info',
        account: 'rYourXRPAccountHere',
      },
    },
  },
})
console.log(res.account_data.Balance);
console.log(res.account_data.OwnerCount);

Getting the available balance

The balance you get from the response is not the available balance that the account has to spend.

Each account has a reserve:

• Base reserve: 10 XRP

• Owner reserve: 2 XRP per item

So to get the available balance in drops:

To learn more visit:

Converting drops to XRP

A drop is the minimum amount valid in the XRP Ledger, each drop is equal to 0.000001 XRP.

You can easily convert drops to xrp with xrpl.js.

Submitting Transactions

Making a Payment

To send XRP from one account to another, you can submit a payment transaction:

provider.request({
  method: 'wallet_invokeSnap',
  params: {
    snapId: 'npm:xrpl-snap',
    request: {
      method: 'xrpl_signAndSubmit',
      params: {
        TransactionType: 'Payment',
        Account: 'rYourXRPAccountHere', // The Snap's XRP account
        Destination: 'rRecipientXRPAccountHere',
        Amount: '1000000', // 1 XRP in drops
      },
    },
  },
})

This transaction sends 1 XRP from your account to the specified destination account.

Creating a Trustline

A trustline is required to hold tokens issued by other accounts on the XRP Ledger. Here’s how to create a trustline:

provider.request({
  method: 'wallet_invokeSnap',
  params: {
    snapId: 'npm:xrpl-snap',
    request: {
      method: 'xrpl_signAndSubmit',
      params: {
        TransactionType: 'TrustSet',
        Account: 'rYourXRPAccountHere',
        LimitAmount: {
          currency: 'TOKEN', // Add the currency of the Token fe. USD
          issuer: 'rIssuerAccountHere',
          value: '1000', // Maximum amount of the token you can hold
        },
      },
    },
  },
})

This transaction establishes a trustline allowing your account to hold up to 1000 units of a specified token issued by another account.

Sending a Token

Once a trustline is established, you can send tokens to another account as follows:

provider.request({
  method: 'wallet_invokeSnap',
  params: {
    snapId: 'npm:xrpl-snap',
    request: {
      method: 'xrpl_signAndSubmit',
      params: {
        TransactionType: 'Payment',
        Account: 'rYourXRPAccountHere',
        Destination: 'rRecipientXRPAccountHere',
        Amount: {
          currency: 'TOKEN',
          value: '10', // Number of tokens to send
          issuer: 'rIssuerAccountHere',
        },
      },
    },
  },
})

This transaction sends 10 units of the specified token from your account to the recipient's account.

To learn more about the tokens in the XRP Ledger visit:

More examples

If you need more examples about all the transactions that you can submit and how to do it visit:

Submitting an Issue

If you encounter a bug or have a specific issue while using the XRP Ledger Snap, we encourage you to submit an issue through our GitHub repository. By reporting issues, you help us improve the XRP Ledger Snap and address any problems you might be facing. To submit an issue:

Contact Us

If you have any questions or need further assistance, feel free to contact us directly. We are here to help and ensure you have a smooth experience using the XRPL Snap.

• Stay in Touch:

We encourage you to stay connected with us for updates, news, and further support.

1. Connect to MetaMask and get the provider

Before you can install and interact with the XRP Ledger Snap, you need to connect your DApp to MetaMask and retrieve the provider object.

Steps:

2. Connect to MetaMask:

   • In your DApp, prompt the user to connect their MetaMask wallet. This will give you access to the Ethereum provider, which is required to interact with Snaps.

1. Verify that your provider has snaps support

async hasSnapsSupport(provider: MetaMaskInpageProvider): Promise<boolean> {
    try {
      await provider.request({
        method: 'wallet_getSnaps',
      });
      return true;
    } catch {
      return false;
    }
  }

Example:

import type {
  EIP6963AnnounceProviderEvent,
  MetaMaskInpageProvider,
} from '@metamask/providers';

/**
 * Check if the current provider supports snaps by calling `wallet_getSnaps`.
 *
 * @param provider - The provider to use to check for snaps support. Defaults to
 * `window.ethereum`.
 * @returns True if the provider supports snaps, false otherwise.
 */
export async function hasSnapsSupport(
  provider: MetaMaskInpageProvider = window.ethereum,
) {
  try {
    await provider.request({
      method: 'wallet_getSnaps',
    });

    return true;
  } catch {
    return false;
  }
}

/**
 * Get a MetaMask provider using EIP6963. This will return the first provider
 * reporting as MetaMask. If no provider is found after 500ms, this will
 * return null instead.
 *
 * @returns A MetaMask provider if found, otherwise null.
 */
export async function getMetaMaskEIP6963Provider() {
  return new Promise<MetaMaskInpageProvider | null>((rawResolve) => {
    // Timeout looking for providers after 500ms
    const timeout = setTimeout(() => {
      resolve(null);
    }, 500);

    /**
     * Resolve the promise with a MetaMask provider and clean up.
     *
     * @param provider - A MetaMask provider if found, otherwise null.
     */
    function resolve(provider: MetaMaskInpageProvider | null) {
      window.removeEventListener(
        'eip6963:announceProvider',
        onAnnounceProvider,
      );
      clearTimeout(timeout);
      rawResolve(provider);
    }

    /**
     * Listener for the EIP6963 announceProvider event.
     *
     * Resolves the promise if a MetaMask provider is found.
     *
     * @param event - The EIP6963 announceProvider event.
     * @param event.detail - The details of the EIP6963 announceProvider event.
     */
    function onAnnounceProvider({ detail }: EIP6963AnnounceProviderEvent) {
      if (!detail) {
        return;
      }

      const { info, provider } = detail;

      if (info.rdns.includes('io.metamask')) {
        resolve(provider);
      }
    }

    window.addEventListener('eip6963:announceProvider', onAnnounceProvider);

    window.dispatchEvent(new Event('eip6963:requestProvider'));
  });
}

/**
 * Get a provider that supports snaps. This will loop through all the detected
 * providers and return the first one that supports snaps.
 *
 * @returns The provider, or `null` if no provider supports snaps.
 */
export async function getSnapsProvider() {
  if (typeof window === 'undefined') {
    return null;
  }

  if (await hasSnapsSupport()) {
    return window.ethereum;
  }

  if (window.ethereum?.detected) {
    for (const provider of window.ethereum.detected) {
      if (await hasSnapsSupport(provider)) {
        return provider;
      }
    }
  }

  if (window.ethereum?.providers) {
    for (const provider of window.ethereum.providers) {
      if (await hasSnapsSupport(provider)) {
        return provider;
      }
    }
  }

  const eip6963Provider = await getMetaMaskEIP6963Provider();

  if (eip6963Provider && (await hasSnapsSupport(eip6963Provider))) {
    return eip6963Provider;
  }

  return null;
}

*If you are using typescript, you might want to install the package: @metamask/providers

2. Install the XRP Ledger Snap

Once you have connected to MetaMask and obtained the provider, you can proceed to install the XRP Ledger Snap. To install the XRP Ledger Snap call the wallet_requestSnaps method with the npm package of the XRP Ledger Snap: npm:@peersyst/xrpl-snap.

provider.request({
    method: 'wallet_requestSnaps',
    params: {
        ['npm:xrpl-snap']: {},
    },
})

3. Interact with the XRP Ledger Snap

Once the XRP Ledger Snap is installed, you can interact with the XRP Ledger directly from your DApp.

After installation, use the XRP Ledger Snap's API to interact with the XRP Ledger. Below is an example of how to fetch the balance of the connected account.

provider.request({
  method: 'wallet_invokeSnap',
  params: {
    snapId: 'npm:xrpl-snap',
    request: {
      method: 'xrpl_request',
      params: { 
          command: 'account_info', 
          account: 'rBSG8TXQ6nYw1ihh11wRVibnSZP1SeMx7w' // Add your account here
      },
    },
  },
});

To know more about the API of the Snap visit the API reference page

MetaMask Security Model

The XRP Ledger Snap operates within MetaMask’s secure environment, ensuring that your data and assets are protected at all times. Snaps run in a sandboxed environment, meaning they are isolated from your MetaMask account data and other browser extensions. This isolation, combined with a strict permissions model, allows you to control what each Snap can access. Before installing the XRP Ledger Snap, you can review and verify the permissions it requests.

Code Audited by Safer

To further ensure the security of the XRP Ledger Snap, its code has been audited by Safer, a leading blockchain security firm. Safer’s comprehensive audit covered the entire codebase, identifying and addressing potential vulnerabilities to ensure the Snap operates securely within MetaMask. The Snap is also subject to continuous monitoring and updates, ensuring that it remains secure against any emerging threats over time.

Secure Network Interactions with xrpl.js

In addition to these safeguards, the XRP Ledger Snap utilizes the well-audited xrpl.js library to interact with the XRP Ledger network. This library is trusted by the XRP Ledger developer community and is regularly updated to incorporate the latest security enhancements. By using xrpl.js, the XRP Ledger Snap ensures that all interactions with the XRP Ledger are conducted securely and reliably, providing you with peace of mind while managing your XRP and other tokens.

This section provides a comprehensive guide on how to use the XRPL Snap API. It covers installation, interaction with the XRPL Snap, network management, and handling transactions, including exporting the private key.

Installation

To install the XRP Ledger Snap in your MetaMask environment, use the following request:

provider.request({
  method: 'wallet_requestSnaps',
  params: {
    ['npm:xrpl-snap']: {},
  },
});

For Development: If you are developing the XRP Ledger Snap locally, use this request to install it from your local environment:

provider.request({
  method: 'wallet_requestSnaps',
  params: {
    ['local:http://localhost:8080']: {},
  },
});

Interact with the Snap

Once the XRP Ledger Snap is installed, you can interact with it using the following methods:

Making RPC Requests

You can interact with the XRP Ledger via the Snap by sending RPC requests. Here is an example:

provider.request({
  method: 'wallet_invokeSnap',
  params: {
    snapId: 'npm:xrpl-snap',
    request: {
      method: 'xrpl_request',
      params: { 
        command: 'account_info', 
        account: 'rBg...' // Add your account here
      },
    },
  },
});

This example requests account information from the XRP Ledger.

Network Management

Get Supported Networks

To retrieve a list of networks supported by the XRPL Snap:

provider.request({
  method: 'wallet_invokeSnap',
  params: {
    snapId: 'npm:xrpl-snap',
    request: {
      method: 'xrpl_getSupportedNetworks',
    },
  },
});

Get Current Network

To check the currently active network:

provider.request({
  method: 'wallet_invokeSnap',
  params: {
    snapId: 'npm:xrpl-snap',
    request: {
      method: 'xrpl_getActiveNetwork',
    },
  },
});

Change the Selected Network

To switch to a different network:

provider.request({
  method: 'wallet_invokeSnap',
  params: {
    snapId: 'npm:xrpl-snap',
    request: {
      method: 'xrpl_changeNetwork',
      params: { 
        chainId: 1  // Replace with the correct chainId for the desired network
      },
    },
  },
});

Signing and Submitting Transactions

The XRP Ledger Snap allows you to sign and submit transactions directly from your DApp.

Sign and Submit a Transaction

To sign and submit a transaction to the XRP Ledger:

provider.request({
  method: 'wallet_invokeSnap',
  params: {
    snapId: 'npm:xrpl-snap',
    request: {
      method: 'xrpl_signAndSubmit',
      params: {
        TransactionType: 'Payment',
        Account: 'rBg...',     // Your account address
        Destination: 'rPT...', // Destination address
        Amount: '1000000',     // Amount in drops (1 XRP = 1,000,000 drops)
      },
    },
  },
});

Sign a Transaction Without Submitting

If you only need to sign a transaction without submitting it to the network:

provider.request({
  method: 'wallet_invokeSnap',
  params: {
    snapId: 'npm:@peersyst/xrpl-snap',
    request: {
      method: 'npm:xrpl-snap',
      params: {
        TransactionType: 'Payment',
        Account: 'rBg...',
        Destination: 'rPT...',
        Amount: '1000000', // Amount in drops
      },
    },
  },
});

Export Private Key

To display the user's private key in the XRP Ledger Snap use this method.

provider.request({
  method: 'wallet_invokeSnap',
  params: {
    snapId: 'npm:xrpl-snap',
    request: {
      method: 'xrpl_extractPrivateKey',
      params: undefined,
    },
  },
})