Odos Widgets

Overview

The odos-widgets library is a set of React components for third-party dApps to facilitate Odos functionality directly on their UI.

View published versions on NPM

View releases on GitHub

Installation

npm install odos-widgets

OdosSwapWidget

The OdosSwapWidget is a configurable React component that enables third-party apps to facilitate Odos-powered swaps directly on their UI.

Props

Property	Required	Description	Default value
chainIds	No	An array of chain IDs that tells the widget what chains to render. Defaults to all Odos-supported chains.	[1, 10, 56, 137, 146, 250, 252, 324, 5000, 8453, 34443, 42161, 43114, 59144, 534352]
rpcUrlMap	No	Mapping of JSON-RPC endpoint URL strings, indexed by chain ID ℹ️ If rpcUrlMap is omitted, public RPC URLs will be used for all chains in chainIds. ℹ️ If you provide an rpcUrlMap that includes only some chains in chainIds, public RPC URLs will be used for the rest.	Public RPC URLs
theme	No	Object of properties to set custom styling. ℹ️ If theme is omitted, the default Odos theme will be applied. ℹ️ If you specify only a subset of the available theme properties, default values will be used for the unspecified properties.	Odos theme
referralCode	No	The code you registered to participate in the Odos partner referral program. ℹ️ If you, or someone on your team, have not registered a referralCode, consider doing so to get the most out of your Odos integration.	1
wagmiConfig	No	A wagmi config object. This allows users to only have to connect their wallet in the parent app, because the widget inherits the connection. ⚠️ If wagmiConfig is passed, do not pass the rpcUrlMap or chainIds props.	undefined
tokenWhitelistMap	No	Mapping of whitelisted token address arrays, indexed by chain ID. Tokens outside these lists will be excluded.	undefined
defaultInputTokenMap	No	Mapping of default input token addresses, indexed by chain ID. This is used to preselect an input token by default.	undefined
defaultOutputTokenMap	No	Mapping of default output token addresses, indexed by chain ID. This is used to preselect an output token by default.	undefined
staticInputTokenMap	No	Mapping of static input token addresses, indexed by chain ID. If specified, this is used to preselect an input token that cannot be changed by the user.	undefined
staticOutputTokenMap	No	Mapping of static output token addresses, indexed by chain ID. If specified, this is used to preselect an output token that cannot be changed by the user.	undefined

ℹ️ If you want to specify a chain's native token in any of the token map props, use the zero address: 0x0000000000000000000000000000000000000000.

Theme properties

Property	Default value	Type
maxWidth	430	number
fontFamily	"Montserrat, sans-serif"	string
textColor100	"#ffffff"	string
textColor200	"#E8E8E8"	string
textColor300	"#AFB3B5"	string
accentTextColor	"#ffffff"	string
accentColor	"#FC7E3D"	string
successColor	"#66E86B"	string
errorColor	"#FF3232"	string
warningColor	"#F6DB49"	string
backgroundColor100	"#43494A"	string
backgroundColor200	"#262F31"	string
backgroundColor300	"#13191B"	string
backgroundColor400	"#000607"	string
wcThemeMode	"dark"	"light" | "dark"

Usage

import React from "react";
import { OdosSwapWidget } from "odos-widgets";

function YourAppComponent() {
  // Must have length >= 1
  const chainIds = [
    1, 137,
    // ... more Odos-supported chain IDs
  ];

  // Must have length >= 1
  const rpcUrlMap = {
    1: "https://ethereum-rpc-example",
    137: "https://polygon-rpc-example",
    // ... more Odos-supported chains
  };

  // Your custom theme
  const theme = {
    maxWidth: 430,
    fontFamily: "Montserrat, sans-serif",
    // ... more theme properties
  };

  // Each array must have length >= 2
  const tokenWhitelistMap = {
    1: [
      "0x0000000000000000000000000000000000000000",
      "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "0xdAC17F958D2ee523a2206206994597C13D831ec7",
      // ...
    ],
    137: [
      "0x0000000000000000000000000000000000000000",
      "0x0d500B1d8E8eF31E21C99d1Db9A6444d3ADf1270",
      "0x8f3Cf7ad23Cd3CaDbD9735AFf958023239c6A063",
      // ...
    ],
    // ...
  };

  // Your default input token for each supported chain
  const defaultInputTokenMap = {
    1: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    137: "0x8f3Cf7ad23Cd3CaDbD9735AFf958023239c6A063",
    // ...
  };

  return (
    <div>
      <OdosSwapWidget
        chainIds={chainIds}
        rpcUrlMap={rpcUrlMap}
        theme={theme}
        tokenWhitelistMap={tokenWhitelistMap}
        defaultInputTokenMap={defaultInputTokenMap}
      />
    </div>
  );
}

export default YourAppComponent;

Example apps

The Odos team maintains a repo with example apps for different frameworks like Next.js and Create React App. Please refer to this repo to see how the OdosSwapWidget is implemented and more.

Development

Format and lint project

npm run format

npm run lint

Unit testing

To run all unit tests, run

npm run test

To run a specific unit test, run

npm run test:match <name-of-test-file>

Empirical testing

There are two ways to empirically test locally:

1. Via npm link, which directly links a consuming app to the odos-widgets source code. This is the fastest way to test.
2. Via npm pack, which fully bundles the odos-widgets package and outputs a bundled .tgz file in the root directory of this project. This package can then be installed in a consuming app.

Note: The consuming app can be a separate local app, like a template Next.js app, or similar,

npm link

In the root directory of this project, run

npm run build
npm link

In the consuming app, run

npm link odos-widgets

After the initial link is made, simply run npm run build in the odos-widgets project. This will update the package code used by the consuming app. There is no need to re-link, unless the link is broken for some reason.

npm pack

Since npm link doesn't test bundling, using npm pack is the best way to test the bundling and functionality of the fully bundled package locally, second only to actually publishing it. This method involves generating a bundled .tgz file locally, and installing it directly in the consuming app.

In the root directory of this project, run

npm run pack

In the consuming app, run

npm install <relative-path-to-output-package.tgz>

Contribution workflow

1. Make edits on a branch, like my_feat.
2. Create a PR for my_feat.
3. When the PR is ready, merge my_feat into beta and delete my_feat.
4. GitHub Actions will release a beta version.
5. If the beta is good, merge beta branch into main.
6. Github Actions will release a main version.

⚠️ Remember to pull the beta or main after a new release to fetch the latest changelog and version that the release bot committed.

Commit convention

Commit messages must follow Conventional Commits, as they are tied to the package versioning when merging to the beta or main branch.

The current CI config enforces these guidelines. To be guided through the commit process, run

npm run commit

To update the commit types shown below, see cz-commits.js. To update how these commit types relate to package versioning, see .releaserc.js

Label	Description
build	Changes that affect the build system or external dependencies
chore	Other changes that don't modify src or test files
ci	Changes to our CI configuration files and scripts
docs	Documentation only changes
feat	A new feature
fix	A bug fix
perf	A code change that improves performance
refactor	A code change that neither fixes a bug nor adds a feature
revert	Reverts a previous commit
style	Changes that do not affect the meaning of the code (white-space, formatting, etc)
test	Adding missing tests or correcting existing tests