Compass Widget

Blockend Widget is a single-line-of-code integration which enables dapps to access users liquidity from across tokens, chains, and networks giving dapps higher market penetration and in-turn allowing more people to access the world of crypto and decentralized apps.

Installation

Blockend Widget is available as an npm package along with several required dependencies for full functionality.

Package Dependencies Overview

The widget requires the following dependency packages:

• @dynamic-labs: Provides wallet connection and authentication capabilities.
• @cosmjs: Enables interaction with Cosmos-based blockchains
• @walletconnect: An open-source protocol that enables secure wallet connections between dApps and mobile wallets.

Installation Commands

Choose your preferred package manager:

npm:

npm install @blockend/widget @dynamic-labs/sdk-react-core @dynamic-labs/solana @cosmjs/cosmwasm-stargate @cosmjs/proto-signing @cosmjs/stargate @walletconnect/core @walletconnect/modal @walletconnect/universal-provider

yarn:

yarn add @blockend/widget @dynamic-labs/sdk-react-core @dynamic-labs/solana @cosmjs/cosmwasm-stargate @cosmjs/proto-signing @cosmjs/stargate @walletconnect/core @walletconnect/modal  @walletconnect/universal-provider

Note: All dependencies are required for full functionality of the widget across different blockchain networks and wallet types.

Getting started with Blockend Widget

Integrating widget to your dapp or webiste is very easy. It takes a full 3 line of code to integrate and start using Blockend Widget, now that's a lot of work for a human dev.

1. Import Widget dependencies

In your react app, start by importing the Blockend Widget and its styles

Copy

import Blockend from "@blockend/widget";
import "@blockend/widget/dist/style.css";

You may encounter Server Error... ReferenceError: self is not defined in your Next JS app, this is because blockend requires web apis to work and the web apis are not available on the server side when next js renders a page, in order to avoid this you can start by importing the Blockend Widget like below

Copy

import dynamic from "next/dynamic";
const Blockend = dynamic(() => import("@blockend/widget"), {
  ssr: false,
});
import "blockend/dist/style.css";
```

#### Next.js Minification Issue

When using the widget with Next.js, you may encounter a variable naming conflict error ("n is already declared") if you have `swcMinify` enabled. This is due to a minification conflict between Next.js's SWC compiler and the widget's bundled code.

To resolve this issue, disable SWC minification in your `next.config.js`:

```js
/** @type {import('next').NextConfig} */
const nextConfig = {
  swcMinify: false, // Temporarily disable SWC minification
  // ... other configs
};

export default nextConfig;

Note: This is a temporary workaround. We are actively working on resolving this minification conflict in future versions of the widget to ensure full compatibility with Next.js's default settings.

Class extends value /static/media/client.98866d6736d9f36d61b8.cjs is not a constructor or null
TypeError: Class extends value /static/media/client.98866d6736d9f36d61b8.cjs is not a constructor or null

If you encounter the above error, add this code to your package.json file

"resolutions": {
    "rpc-websockets": "7.10.0",
    "@solana/web3.js": "1.91.6"
}

for more details please refer https://docs.dynamic.xyz/troubleshooting/react/cannot-resolve-rpc-websockets

2. Initialize the Widget

Add the widget component to your app

Copy

<Blockend />

Integrator Id (Required)

Unique identifier assigned to each integration partner. It is used to track and manage various integrations within our system. Error will be thrown if this field is empty.

Copy

const configuration = {
  integratorId:""
  ...
};
<Blockend  configuration={configuration} />

This id will be added in the request header of api calls that is made by the widget.

And that is it, you have successfully integrated the Blockend Widget.

3. (optional) Customizing the Widget

As an optional step, you can also customize the look and feel of the widget. This can be done by passing a configuration object as prop when initializing the widget.

Copy

const configuration = {
    gradientStyle: {
    background: "linear-gradient(#E66465, #9198E5)",
    spinnerColor: "#E66465",
    stopColor: "#9198E5",
  },
  containerStyle:{
    background:"#000000",
    border:"1px solid #fff",
    boxShadow:"1px 1px 7px 5px rgb(255,255,255,0.1)" ,
  },
  theme:"light",
   headingText: "",
      headingContainerStyles: {
        transform: "skewX(0deg)",
        left: "0px",
        top: "0px",
      },
      headingStyles: {
        transform: "skewX(0deg)",
      },
  customTheme: {
    text: {
      primary: "#808080",
      secondary: "rgba(128, 128, 128, 0.75)",
      placeholder: "#cccccc",
      success: "#49AD71",
      error: "#FD5868",
    },
    background: {
      container: "#FFFFFF",
      secondary: "#E9E9E9",
      card:"#FFFFFF",
      networkCard: "#F6F6F6",
      loaderbar: "#E9E9E9",
      coin:"#E0E0E0",
      rewards:"#eaeaeb33"
    },
    border: {
      primary: "#E0E0E0",
      inputHighlight: "#9FC966",
    },
    fontFamily:'"micro 5 charted"', sans-serif, lato;
    shadow: {
      boxShadow: "1px 1px 7px 5px rgb(255,255,255,0.1)",
    },
  },
};

<Blockend configuration={configuration} />;

Full list of configuration options can be found here

Configuration Options

Customizing gradient colors

You can customize the gradient colors of the widget by passing gradientStyle object in configuration.

Copy

const configuration = {
  gradientStyle: {
    background: "linear-gradient(#E66465, #9198E5)",
    spinnerColor: "#E66465",
    stopColor: "#9198E5",
  },
  ...
};

You can customize the theme of the widget by passing customTheme object in configuration.

Copy

const configuration = {
  // containerStyle will override the styles written for the widget container, containerStyle accepts all the inline style properties.
  containerStyle:{
    background:"#000000", // changes the background color of the widget to black
    border:"1px solid #fff", //adds border to the widget container
    boxShadow:"1px 1px 7px 5px rgb(255,255,255,0.1)" // for adding desired shadow effect to the container.
  },
  theme:"light",  // light or dark, if custom theme is applied then custom theme will override light/dark theme
     headingText: "", // Text to display as the widget heading - pass the heading as string to display your own heading, default text is LAZY.exchange.
      headingContainerStyles: {// Styles to customize the container that wraps the heading,
        transform: "skewX(0deg)", // Supports all valid CSS style properties.
        left: "0px",
        top: "0px",
      },
      // Styles to customize the heading text itself,
      // Supports all valid CSS style properties.
      headingStyles: {
        transform: "skewX(0deg)",
      },
  customTheme: {
    text: {
      primary: "#808080", // primary color of the theme, this applies to headings, main text, svgs, etc..,
      secondary: "rgba(128, 128, 128, 0.75)",  //secondary color of the theme, this applies to secondary headings, network names, route info ,etc..,
      placeholder: "#cccccc",// to update  placeholder colors like input placeholder,date picker heading etc.,
      success: "#49AD71", // view all routes Higher output color
      error: "#FD5868", // error messages and lower output.
    },
    background: {
      container: "#FFFFFF", // can be used to update the bg color of the widget container, input amount container and routes container.
      secondary: "#E9E9E9", // can be used to update the table cell background on portfolio page.
      card:"#FFFFFF", //can be used to update the card color of the widget
      networkCard: "#F6F6F6", // used as background color for top main networks cards and transaction hash container in tokens section.
      loaderbar: "#E9E9E9", // loader bar color accross the widget.
      coin:"#E0E0E0", // used to update th default background color of the coin and chain icons.
      rewards:"#eaeaeb33" // can be used to update the rewards section background color on history page
    },
    border: {
      primary: "#E0E0E0",// primary border color of the widget, can be used to update the container border,border of coin and chain icons, cards border of the widget.
      inputHighlight: "#9FC966", //inputHighlight is used to update the border color of search tokens input field on select chains page when there are more than 0 results.
    },
    fontFamily:'"micro 5 charted"', sans-serif, lato; // can be used to update the font family of the widget to match the parent site, add the fonts to your site and just pass the font name to the widget.
    shadow: {
      boxShadow: "1px 1px 7px 5px rgb(255,255,255,0.1)", // to add shadow effect to the container and cards.
    },
  },
};

Setting Default Chains and Tokens

Widget gives you the option to set default chains and tokens to be shown to the user. This can be done by passing defaultChains and defaultTokens in configuration when initializing the widget. See list of supported chains and tokens below.

Copy

const configuration = {
  defaultChains: {
    from: { chainId: "10" }, // optimism
    to: { chainId: "sol" }, // solana
  },
  defaultTokens: {
    from: { tokenAddress: "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee" }, // eth on optimism
    to: { tokenAddress: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" }, // usdc on solana
  },
  ...
};

Note: token address for native tokens is set to 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee

Here is what a integration of widget on your frontend might look like:

Copy

import Blockend from "@blockend/widget";
import "@blockend/widget/dist/style.css";

const configuration = {
  gradientStyle: {
    background: "linear-gradient(#e66465, #9198e5)",
    spinnerColor: "#e66465",
    stopColor: "#9198e5",
  },
  defaultChains: {
    from: { chainId: "10" }, // optimism
    to: { chainId: "sol" }, // solana
  },
  defaultTokens: {
    from: { tokenAddress: "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee" }, // eth on optimism
    to: { tokenAddress: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" }, // usdc on solana
  },
};

export const Home = () => {
  return <Blockend configuration={configuration} />;
};