Stellar Wallet Integration with MetaMask Snaps

This guide provides detailed instructions on integrating Stellar wallet functionalities into MetaMask Snaps, enabling seamless interaction with Stellar applications. This integration aims to create a universal standard for integrating Stellar wallet functionalities across different applications.

Table of Contents

• Quick Start
  • ✨ Connect and Install
  • ✨ Calling Stellar Methods
    • 🟠 Get Wallet Data
    • 🌐 Specify a Network
    • 🔏 Easily Signing a Transaction
• Calling Stellar RPC Methods
• Stellar Methods
• Conclusion

Quick Start

Follow these steps to get started with integrating Stellar-Wallet functionalities into your MetaMask Snaps.

✨ Connect and Install

1. Set Up MetaMask Flask: Ensure you have MetaMask Flask installed, which is a version tailored for developers to create and integrate Snaps.

2. Install Metastellar Snap: Follow the installation instructions provided in the Metastellar Documentation to connect your MetaMask to the Stellar network.

3. Create Your Snap: Use the MetaMask Snaps CLI to initialize a new Snap project. Refer to the MetaMask Snaps documentation for detailed guidance on setting up your environment. Installation To install Stellar Snap, clone the repository and install the necessary dependencies:

git clone https://github.com/yourusername/stellar-snap.git
cd stellar-snap
yarn install

To run the application, execute:

yarn start

This command starts the application and opens the user interface for interaction.

Connecting to MetaMask

To connect Stellar Snap to MetaMask, use the following method:

const result = await ethereum.request({
  method: 'wallet_requestSnaps',
  params: {
    [`npm:stellar-snap`]: {}
  },
});

Invoking Stellar Wallet Methods

You can invoke Stellar wallet methods using the following structure:

const result = await ethereum.request({
  method: 'wallet_invokeSnap',
  params: {
    snapId: `npm:stellar-snap`,
    request: {
      method: `${methodName}`,
      params: {
        paramName: `${paramValue}`
      }
    }
  }
});

Calling Stellar Wallet Functions from Other MetaMask Snaps

To call Stellar-Wallet functions from other MetaMask snaps, you need to ensure that the Snap containing the Stellar wallet is installed and running. You can then use the wallet_invokeSnap method to access its functions.

Example Assuming you have another Snap that needs to call the getBalance method from Stellar Snap, you can do this:

const balance = await ethereum.request({
  method: 'wallet_invokeSnap',
  params: {
    snapId: `npm:stellar-snap`,
    request: {
      method: 'getBalance',
      params: {
        address: 'your-stellar-address', // replace with the actual Stellar address
        testnet: false // optional; true for testnet
      }
    }
  }
});
console.log('Balance:', balance);

Important Notes

1. Error Handling: Always implement error handling for network requests to manage any exceptions or issues that may arise.

2. Snap ID: Ensure that you are using the correct Snap ID (e.g., npm:stellar-snap) when invoking methods.

3. Asynchronous Calls: The requests to the Snap are asynchronous, so make sure to use async/await or .then() for handling promises.

✨ Calling Stellar Methods

Integrating Stellar functionalities allows applications to leverage important wallet features. Below are key methods for interaction:

🟠 Get Wallet Data

Retrieve essential information related to the user's Stellar wallet.

const address = await callMetaStellar('getAddress');
console.log(`Current Address: ${address}`);

🌐 Specify a Network

Set the network environment for transactions, ensuring users connect to the appropriate Stellar network (Mainnet or Testnet).

await callMetaStellar('setNetwork', { network: 'testnet' });

🔏 Easily Signing a Transaction

Enable users to securely sign transactions to ensure authorized actions.

const signedTransaction = await callMetaStellar('signTransaction', { xdr });
console.log(`Signed Transaction: ${signedTransaction}`);

Calling Stellar RPC Methods

Copy the callMetaStellar Function

The easiest way to interact with the wallet is by copying the callMetaStellar function. This function acts as a bridge to make calls to the Stellar RPC methods defined in your Snap.

async function callMetaStellar(method, params) {
  const provider = window.ethereum; // Access the MetaMask provider
  return await provider.request({
    method: `metastellar_${method}`,
    params: [params],
  });
}

Invoke the callMetaStellar function:

// Connect
const connected = await callMetaStellar('connect');

// Get Address
const address = await callMetaStellar('getAddress'); 

// Sign Transaction
const params = { transaction: txn, testnet: true };
const signedTxn = await callMetaStellar('signTransaction', params);
// Returns a signed Stellar transaction in XDR as a string

Stellar Methods

Here’s a comprehensive list of Stellar methods available for invocation via the callMetaStellar function. Each function includes a brief description of its purpose and a sample implementation.

1. getAddress

   • Description: Fetch the current Stellar address.
   • Implementation:

   async function getAddress() {
       return await callMetaStellar('getAddress');
   }

2. getAccountInfo

   • Description: Retrieve detailed information about a specific account.
   • Implementation:

   async function getAccountInfo(accountId) {
       return await callMetaStellar('getAccountInfo', { accountId });
   }

3. getBalance

   • Description: Get the current balance of a specific account.
   • Implementation:

   async function getBalance(accountId) {
       return await callMetaStellar('getBalance', { accountId });
   }

4. transfer

   • Description: Initiate a transfer to another account.
   • Implementation:

   async function transfer(destination, amount, assetCode) {
       return await callMetaStellar('transfer', { destination, amount, assetCode });
   }

5. fund

   • Description: Fund an account with Stellar Lumens (XLM).
   • Implementation:

   async function fund(accountId, amount) {
       return await callMetaStellar('fund', { accountId, amount });
   }

6. signTransaction

   • Description: Sign a transaction using the provided XDR.
   • Implementation:

   async function signTransaction(xdr) {
       return await callMetaStellar('signTransaction', { xdr });
   }

7. signAndSubmitTransaction

   • Description: Sign a transaction and submit it to the Stellar network.
   • Implementation:

   async function signAndSubmitTransaction(xdr) {
       return await callMetaStellar('signAndSubmitTransaction', { xdr });
   }

8. getDataPacket

   • Description: Retrieve a data packet for off-chain storage or processing.
   • Implementation:

   async function getDataPacket() {
       return await callMetaStellar('getDataPacket');
   }

9. setCurrentAccount

   • Description: Set the currently selected account.
   • Implementation:

   async function setCurrentAccount(accountId) {
       return await callMetaStellar('setCurrentAccount', { accountId });
   }

10. showAddress

    • Description: Display the current Stellar address to the user.
    • Implementation:

    async function showAddress() {
        return await callMetaStellar('showAddress');
    }

11. createAccount

    • Description: Create a new Stellar account.
    • Implementation:

    async function createAccount() {
        return await callMetaStellar('createAccount');
    }

12. listAccounts

    • Description: List all accounts associated with the wallet.
    • Implementation:

    async function listAccounts() {
        return await callMetaStellar('listAccounts');
    }

13. renameAccount

    • Description: Rename an existing account.
    • Implementation:

    async function renameAccount(accountId, newName) {
        return await callMetaStellar('renameAccount', { accountId, newName });
    }

14. importAccount

    • Description: Import an account using a secret key.
    • Implementation:

    async function importAccount(secretKey) {
        return await callMetaStellar('importAccount', { secretKey });
    }

15. getAssets

    • Description: Retrieve a list of assets held in the wallet.
    • Implementation:

    async function getAssets() {
        return await callMetaStellar('getAssets');
    }

16. sendAuthRequest

    • Description: Send an authentication request to a specific address.
    • Implementation:

    async function sendAuthRequest(destination) {
        return await callMetaStellar('sendAuthRequest', { destination });
    }

17. signStr

    • Description: Sign a string message for verification.
    • Implementation:

    async function signStr(message) {
        return await callMetaStellar('signStr', { message });
    }

18. dispPrivateKey

    • Description: Display the private key for an account.
    • Implementation:

    async function dispPrivateKey(accountId) {
        return await callMetaStellar('dispPrivateKey', { accountId });
    }

19. sendAsset

    • Description: Send a specific asset to another account.
    • Implementation:

    async function sendAsset(destination, amount, assetCode) {
        return await callMetaStellar('sendAsset', { destination, amount, assetCode });
    }

20. createFederationAccount

    • Description: Create a new federation account for easier asset management.
    • Implementation:

    async function createFederationAccount(name) {
        return await callMetaStellar('createFederationAccount', { name });
    }

These functions form the core of your Stellar wallet integration within MetaMask Snaps. By utilizing these methods, you enable smooth interaction with Stellar features, fostering a cohesive user experience across applications.

Conclusion

By following this guide, you can effectively integrate Stellar wallet functionalities into your MetaMask Snaps. This modular approach enhances your application while establishing a universal standard for Stellar wallet integration, allowing other developers to easily adopt the framework.