Run the MetaMask Snap

The MetaMask Snap for VSL lets you interact with the Verifiable Settlement Layer (VSL) from within MetaMask-enabled dApps. Once installed, the Snap acts as a secure interface between MetaMask and your local VSL node, giving you tools to create and manage accounts, mint and transfer assets, make payments, and even sign and submit verifiable claims.

This guide provides a high-level overview of how the Snap works and how to get it running. For detailed installation instructions, head directly to the appropriate folders in the VSL Snap GitHub repository.

What is the VSL MetaMask Snap?

The Snap is a custom MetaMask plugin that extends MetaMask's capabilities through its Snap system, allowing it to communicate with external chains and tools. In this case, it connects with a locally running VSL node via JSON-RPC.

Under the hood:

• The Snap is a Node.js app that listens for wallet_invokeSnap and keyring_* RPC calls.

• These RPC methods let your dApp (or browser interface) perform VSL-specific actions such as:

  • Creating and exporting accounts

  • Minting and transferring tokens

  • Submitting payment claims

  • Viewing balances across native and custom assets

During development, the Snap provider is served from localhost:8080, and it communicates with your local VSL node running on localhost:44444. However, the Snap itself always runs inside MetaMask’s contained extension environment, not in your local server.

In production, the Snap is installed via the npm registry and communicates with a remote VSL node (typically a public endpoint), making it usable without any local setup.

Why Use It?

By running the Snap, developers can:

• Interact with VSL accounts directly from MetaMask Flask, the developer version of MetaMask

• Avoid writing custom frontends for basic VSL operations

• Leverage Snap’s secure key management and interface to safely test cross-chain interactions

• Extend their existing dApps to use VSL settlement features

This makes the Snap a bridge between your frontend UI and VSL’s off-chain verifiability model.

How it Works (Behind the Scenes)

1. Local Development Server: The Snap runs a dev server at localhost:8080, hosting the Snap interface and logic.

2. MetaMask Flask Integration: You install the Snap via MetaMask Flask, enabling your browser wallet to run the plugin.

3. JSON-RPC Bridge: dApps or scripts use wallet_invokeSnap to trigger actions. These actions are routed through the Snap and forwarded to the VSL node.

4. Secure Signing: The Snap handles message signing and account management using its own internal state (not MetaMask’s Ethereum accounts).

You’ll need to disable browser CORS for Snap-to-node communication during local development.

How Snap Setup Works

The VSL Snap is made up of two main components:

• Snap: The core logic that runs inside MetaMask’s sandboxed environment.

• Companion: A UI server (built with Next.js) that allows users to interact with the Snap.

1. Install dependencies

Inside the VSL wallet repository, navigate to the snap folder and install dependencies using npm install. This sets up both the snap and companion packages.

2. Build and publish the Snap

In the snap directory (packages/snap):

• Run npm run build to generate the distribution bundle.

• Before publishing, update the configuration file (config.ts) with:

  • The VSL server address.

  • Any DApp origin URLs that should be allowed to connect to the Snap.

• Then publish the Snap to the npm registry with npm publish. This step is only needed for production use.

Even in development, the Snap runs inside MetaMask. During local testing, the Snap provider is served from localhost:8080, but MetaMask still runs the Snap internally.

3. Run the companion server

The companion package provides a front-end interface:

• For local development, use npm run dev.

• For production, build with npm run build and start with npm run start.

• You may want to run it in the background using a process manager like screen or pm2.

Config Tip: The Snap origin must be correctly configured in the companion app, especially when testing locally. You can’t simply use an IP address—MetaMask requires a valid Snap package origin.

4. Local testing vs Production

• Local testing is much easier and faster—you don’t have to publish the Snap to npm each time.

• Production setup involves publishing the Snap to the npm registry and deploying the companion server to a remote host.

After Setup: What You Can Do

Once the Snap is running and installed, check out the Use MetaMask Integration guide to walk through:

• Creating and managing VSL accounts

• Minting and transferring custom tokens

• Submitting payments and claims

• Signing messages

The Snap interface also offers built-in UI elements to explore these actions without needing custom code.