Getting Started

MIDL JS SDK is a framework for building decentralized applications on Bitcoin, powered by the MIDL Protocol. The MIDL Protocol extends Bitcoin's capabilities, enabling smart contracts and advanced application logic on the Bitcoin network.

It provides a set of tools and libraries to help developers build, test, and deploy smart contracts and Bitcoin-native apps.

VibeHack Participants

Building for the MIDL VibeHack? Head to the VibeHack Guide for a step-by-step walkthrough covering wallet setup, contract deployment, and frontend integration.

Installation

The executor packages allow you to interact with and deploy contracts on the MIDL Protocol from your JavaScript or React application. Install MIDL JS SDK executor packages via your package manager of choice.

pnpm

pnpm add @midl/executor @midl/executor-react @midl/connectors @midl/core @midl/react

npm

npm install @midl/executor @midl/executor-react @midl/connectors @midl/core @midl/react

yarn

yarn add @midl/executor @midl/executor-react @midl/connectors @midl/core @midl/react

Override viem versions

WARNING

This step is required to ensure compatibility with MIDL JS SDK executor. If you skip this step, some features required by MIDL JS SDK may not work as expected.

To ensure compatibility with MIDL JS SDK executor, you need to override the version of viem in your package.json. The patched version of viem provides additional functionality required by MIDL JS SDK executor, such as setting the transaction type, fees, adding estimateGasMulti method and more.

package.json(pnpm)

{
  "pnpm": {
    "overrides": {
      "viem": "npm:@midl/viem"
    }
  }
}

package.json(npm)

{
  "overrides": {
    "viem": "npm:@midl/viem"
  }
}

package.json(yarn)

{
  "resolutions": {
    "viem": "npm:@midl/viem"
  }
}

Example

WARNING

We support wagmi up to version 2.14.16.

Add WagmiMidlProvider to provide the necessary context for the executor to work.

app.tsx

import { MidlProvider } from '@midl/react';
import { WagmiMidlProvider } from "@midl/executor-react";
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

import { midlConfig } from "./midlConfig";

const queryClient = new QueryClient();

function App({ children }: { children: React.ReactNode }) {
    return (
        <MidlProvider config={midlConfig}>
          <QueryClientProvider client={queryClient}>
            <WagmiMidlProvider>
              {children}
            </WagmiMidlProvider>
          </QueryClientProvider>
        </MidlProvider>
    );
}

midlConfig.ts

import {
  createConfig,
  regtest,
} from "@midl/core";
import { xverseConnector } from "@midl/connectors";

export const midlConfig = createConfig({
  networks: [regtest],
  connectors: [xverseConnector()],
  persist: true,
});

Next Steps

• Guide: Deploying Your First Contract
• Guide: Interacting with Contracts