Skip to content

Integration of a swap plugin

Jump to bottom
William Swanson edited this page Mar 2, 2020 · 4 revisions

Edge calls crypto-to-crypto plugins "swap" plugins. If you would like to build one of these plugins, these are the general steps:

  1. Set up your system to build edge-react-gui
  2. Add your plugin to the edge-exchange-plugins repo.
  3. Integrate your new plugin into the wallet.

Building the GUI

Building the wallet begins with the edge-react-gui repo. The instructions in the readme should be more-or-less accurate.

Building React Native applications in general can require a lot of setup. The React Native getting started guide is also a reasonable starting place.

Writing your plugin

Swap plugins live in the edge-exchange-plugins repo. You can see some existing swap plugins implemented in there, like https://github.com/EdgeApp/edge-exchange-plugins/blob/master/src/plugins/changelly.js

Suppose your exchange is called Foo. Your plugin would begin with a makeFooPlugin call, which happens once at app boot. This would accept configuration options (like API keys), and return an instance of your plugin. It also accepts an io object, which provides access to the outside world. You can see the definition of EdgeIo and other data types here: https://github.com/EdgeApp/edge-core-js/blob/49856eb8f053e4883ab3b94f3dcd4069a1ea9a8f/src/types/types.js#L54

Anyhow, your makeFooPlugin returns an EdgeSwapPlugin object. Assuming you don’t need KYC, you only need to implement a single method fetchSwapQuote. This either needs to return an estimate of the number of coins out + mining fee, or some kind of error (SwapAboveLimitError / SwapBelowLimitError / SwapCurrencyError / SwapPermissionLimitError). You can see the error definitions in https://github.com/EdgeApp/edge-core-js/blob/master/src/types/error.js. Since this is just an estimate, there is no need to create a transaction or otherwise commit to doing the swap - it’s just an information query!

If you would like to receive preferential treatment, you can return a locked quote instead of an estimate. In this case, you would set the isEstimate flag to false in your returned EdgeSwapQuote object and treat the returned amount as a firm commitment. You can use the expirationDate flag to say how long the quote is valid for. If the user doesn't want your quote, we will call close on your quote so you can release any locked liquidity.

We use nativeAmount to refer to amounts in Satoshis, Wei, or whatever the smallest integer unit the coin supports. Since coins like Ethereum have too many decimal points for the Javascript number type, a nativeAmount is always a string for accuracy.

Most plugins create a transaction as part of the estimate, since this is a quick & easy way to estimate the fee, but they don’t sign or broadcast the transaction. If the user decides to accept the quote, they will call the approve method on the EdgeSwapPluginQuote. You can use this opportunity to actually commit to the swap & broadcast the transaction. Otherwise, our app will call the close method on any rejected quotes.

Integration

These are the steps you need to simply make the plugin available in the wallet core:

  1. Plugin exists in edge-exchange-plugins
  2. Plugin is exported from edge-exchange-plugins/src/index.js
  3. You have done yarn updot edge-exchange-plugins && yarn prepare inside the edge-react-gui project to copy your local edge-exchange-plugins changes into the GUI.
  4. You have added the plugin to swapPlugins in edge-react-gui/src/util/corePlugins.js
  5. If the plugin depends on ENV.FOO_INIT, you have added a FOO_INIT section to env.json & env.example.json.

API keys

If you plugin depends on API keys, put them into an object called FOO_INIT, then edit env.json and env.sample.json to define this object.

Logos

The Edge GUI expects to find logos for your plugin at src/assets/images/exchange/index.js. You will need to provide the following sizes:

  • 200 x 70
  • 400 x 140 (@2x)
  • 600 x 210 (@3x)

You will also need to provide a 64 x 64 icon for the settings screen.

Put all these images into that folder, and then edit index.js to export them.

KYC

If you need KYC, look around for SwapActivateShapeshiftScene, SwapVerifyShapeshiftModal, or SwapVerifyChangellyModal for some examples of how we handle this. Shapeshift requires KYC before they will even return a quote, but Changelly requires a terms-of-service agreement after it gives a quote, but before the user can accept the quote.

Clone this wiki locally