1 of 20

REDSHIFT API Documentation

Welcome to the REDSHIFT API

This documentation is your entry point to interacting with submarine swaps programmatically on REDSHIFT

What is REDSHIFT?

REDSHIFT is a payment network tool that allows Lightning Network payments to be made using on-chain assets like Bitcoin, Ethereum, and ERC-20 tokens.

It utilizes a technology called Submarine Swap in order to make payments in a trustless way - meaning the on-chain asset is controlled by the original owner until the Lightning Payment is sent.

Why is this useful?

There are a number of use cases for using Submarine Swaps to make Lightning Network payments:

Channel Rebalancing: The payment channels that compose the Lightning Network require maintaining sufficient liquidity in order to send and receive payments. REDSHIFT allows the liquidity within these channels to be adjusted without having to close and re-open channels with peers - avoiding on-chain opening and closing fees and maintaining the channel's successful payment routing history. Essentially, you can "top up" your local channel balance with REDSHIFT.

Merchants: Accept more digital currencies without adding additional infrastructure. If you already accept Lightning Network payments, REDSHIFT enables your customers to pay using other currencies while you still receive payment in LBTC.

Consumers: REDSHIFT allows customers to send payments on the Lightning Network without having to operate their own node or trust custodial wallets with their sats. Simply send on-chain assets from the wallet they already use and the Lighting Network invoice will be paid.

How does it work?

Submarine Swaps utilize a class of payments called Hash Time Locked Contracts (HTLCs).

HTLCs use hashlocks and timelocks to require that the receiver of a payment either acknowledge receiving the payment prior to a deadline by generating cryptographic proof of payment or forfeit the ability to claim the payment, returning it to the payer.

HTLCs are what make REDSHIFT trustless - neither the payer or receiver need to trust that the other party will make their required payment because ownership conditions are baked into the transaction itself.

Routing Node Example Workflow

Alice runs a Lightning Network node that helps route payments through the Lightning Network. She has opened a couple of channels with a handful peers and has been routing payments through them. After a few days, a lot of her balance has accrued on the remote side of her channels.

Instead of closing her lopsided channels and reopening them to regain more local balance, she generates an invoice for her channels with more remote capacity and sends it to REDSHIFT via REDSHIFT's API. REDSHIFT responds with a Bitcoin address and amount to send to the address.

Note: The amount of satoshis Alice will send to the address is typically greater than the amount of satoshis on the invoice. So in Alice's case, she might have to send 100,500 satoshis on-chain in order to fulfill her 100,000 sat invoice. This spread is how liquidity providers (the people paying the Lightning Invoice) make money and cover the cost of the on-chain transaction required to claim their funds after paying the Lightning Invoice that Alice provided.

Alice sends the Bitcoin to the prescribed address and her Lightning Invoice gets paid, pushing the remote balance of the channel back over to her local side, enabling her to send more outgoing payments through the channel without having to close and reopen it.

Merchant / Consumer Example Workflow

Alice wants to pay a 100,000 satoshi Lightning Network invoice with an on-chain asset like Ether. She sends the invoice to REDSHIFT via the REDSHIFT API or a REDSHIFT widget embedded on a webpage. REDSHIFT responds with an unsigned Ethereum transaction, which contains the contract address, input data, and amount of ether to send.

Note: The amount of value of the Ether Alice will send to the address is typically greater than the value of satoshis on the invoice. Let's say that one satoshi is worth $1 and one Ether is worth $1. In this case, Alice might have to send 103,000 Ether on-chain in order to fulfill her 100,000 sat invoice. This spread is how liquidity providers (the people paying the Lightning Invoice) make money and cover the cost of the on-chain transaction required to claim their funds after paying the Lightning Invoice that Alice provided.

Alice sends the prescribed amount of Ether to the address sent back from her REDSHIFT request. These funds are housed in an on-chain escrow protected by HTLCs.

There are now only two ways to claim these funds: either by the liquidity provider using the preimage revealed after paying Alice's Lightning Invoice or by Alice after the timelock has expired.

In most cases, the invoice will be paid and the on-chain asset will be claimed by the liquidity provider. If the invoice is unable to be paid, Alice will be able to re-claim her funds after the timelock expires. This isn't typical but can happen if a route cannot be found.

Getting Started

Definitions

There is a lot of language native to submarine swaps

Foundational Definitions

Submarine Swap - an atomic on-chain to off-chain swaps of cryptocurrencies. REDSHIFT currently supports swaps of on-chain assets like Bitcoin, Ether, or DAI for Lightning Bitcoin. Also referred to as just "swap".

HTLC (Hash Time Lock Contract) - A type of transaction that puts on-chain funds in escrow until someone unlocks them with a preimage or the timelock expires.

Preimage - A string of characters returned when successfully paying a Lightning Network invoice. Think of it as a password. It is used to unlock on-chain funds that are locked up in an HTLC.

Liquidity Provider - The counter-party to a swap that will pay the Lightning Invoice in exchange for an on-chain asset like Bitcoin, Ether, or DAI.

Quote - The price a liquidity provider returns when asked to pay an invoice. Denominated in the requested asset.

Asset & Market Abbreviations

Asset Abbreviations

onChainTickers

BTC - Bitcoin

ETH - Ether

offChainTickers

LBTC - Lightning Bitcoin (Bitcoin locked up in the Lightning Network)

Market Abbreviations

We combine asset abbreviations with an underscore to define markets in REDSHIFT. We currently support the following mainnet market pairs:

BTC_LBTC - Bitcoin to Lightning Bitcoin

ETH_LBTC - Ether to Lightning Bitcoin

Testnet Market Abbreviations

When working in a testing environment, we append a "T" to the front of UTXO testnet market asset pairs and "K" to Kovan (testnet) Ether market asset pairs. We support the following testnet markets:

TBTC_LTBTC - Testnet Bitcoin to Lightning Testnet Bitcoin

KETH_LTBTC - Testnet Ether to Lightning Testnet Bitcoin

Simnet Market Abbreviations

Like testnet, we append an "S" to the beginning of market assets on simnet. We support the following simnet markets:

SBTC_LSBTC - Simnet Bitcoin to Lightning Simnet Bitcoin

SETH_LSBTC - Simnet Ether to Lightning Simnet Bitcoin

Order States

Funding

WaitingForFundingTx - The HTLC has been created and is waiting for an on-chain funding transaction.

WaitingForFundingTxConfirmation - An on-chain funding transaction has been broadcasted but has not been confirmed.

WaitingForAdditionalFundingTxConfirmation - An on-chain funding transaction has been confirmed but has not met the confirmation threshold required to complete the swap. Wait for more confirmations and the order will move to Funded.

PartiallyFunded - The transaction has been partially funded, meaning a transaction has been sent but the total amount of funds sent has not reached the quote amount. Another transaction must be sent so that the total amount of funding is equal to the amount given in the quote.

Funded - The HTLC has been funded to the correct amount. After quote provider pays the Lightning Invoice, they will receive the preimage to unlock the funds.

Refund

WaitingForRefundTx - The swap was not completed successfully and HTLC's timelock has passed. A transaction can be sent to reclaim funds.

AddressBlacklistedWaitingForRefundTx - The transaction cannot be completed because the address is blacklisted. Send a refund transaction to reclaim funds.

WaitingForRefundTxConfirmation - A refund transaction has been broadcast to the network but has not confirmed yet.

Refunded - The refund transaction has been confirmed and the funds have been sent back to the user.

Other States

Complete - The swap is complete. The invoice has been paid and the funds from the HTLC have been swept by the liquidity provider.

FundWindowElapsed - The window to fund the HTLC has elapsed. Request a new quote to start the swap process again.

Errors

Here is an explanation of the errors you might get returned

Order Errors

OrderNotFound - There is no order in the database with that orderId. Double check that the orderId is correct.

InvalidOrderId - The orderId provided is not a valid UUID. Double check that the orderId is correct.

InvalidRefundAddress - The refund address provided is not a valid Bitcoin address. Double check to make sure the address was input correctly.

Market Errors

InvalidMarket - An invalid market was provided with the request. For valid markets, see Market Documentation.

InvalidOnchainTicker - The asset ticker provided is not valid. For valid tickers, see Asset Abbreviation documentation.

Invoice Errors

InvalidInvoice - The invoice provided is not a valid Lightning Network invoice. You can decode valid Lightning Network invoices using RADAR ION's invoice decoder.

InvoiceExpiresTooSoon - The invoice provided expires too soon.

InvoiceAmountBelowMinimum - Invoice is below the minimum amount for selected market.

InvoiceAmountAboveMaximum - Invoice is above the maximum amount for selected market.

InvoicePaymentNotRoutable - There is no route between the liquidity provider and the invoice recipient. Usually a result of the invoice recipient not having a well connected Lightning node. Can be resolved by having the invoice recipient open a channel to another well connected node like RADAR ION's.

TooManySwapsInFlight - There are too many swaps happening at once. Can be resolved by waiting and sending another request.

Broadcast Transaction

InvalidSignedTxHex - The signed transaction hex is invalid. Double check the transaction hex or generate a different one.

InvalidNetworkOrSubnet - The provided network or subnet is not valid. See

InactiveNetworkOrSubnet - The provided network or subnet is not active.

Other Errors

InternalServerError - There was an error during one of the requests. Retry the request.

NoQuoteProvidersAvailable - There are no quote providers available for the particular market. This is very unusual. Contact support or wait and retry request.

Tutorials

Tutorials to get a project up and running using the REDSHIFT API

Ether Swap Tutorial

In this tutorial, we'll integrate the REDSHIFT Javascript SDK into a Vue frontend that can be used to execute a Kovan Testnet Ether (kETH) <-> Lightning Testnet Bitcoin (ltBTC) submarine swap.

Prerequisites

Install MetaMask

MetaMask is an Ethereum wallet and web3 provider running inside a browser extension. Install MetaMask if not already installed. You can request testnet ether from https://faucet.kovan.network if you do not have any.

Clone this repository

git clone https://github.com/RadarTech/redshift-monorepo.git

Navigate to the sample project directory

cd redshift-monorepo/samples/sdk-usage-vue

Install dependencies

yarn

Run the application

yarn start

Facilitating a Swap

Overview

In this scenario, a user arrives at the app with a Lightning invoice that they would like REDSHIFT to pay in exchange for ETH. The exchange is atomic and completely trustless. The user will send their ETH to the swap contract, which can only be claimed by REDSHIFT once the invoice has been paid. If REDSHIFT fails to pay the invoice, the user can reclaim their funds from the contract after a couple hours.

Fetch Initial Information

We'll begin by taking a look at the Start page.

First, we must fetch two important pieces of information from REDSHIFT: The active markets and market requirements.

The markets are rather self-explanatory. They tell us which markets REDSHIFT is currently servicing.

The market requirements can help inform us if the invoice will be rejected by REDSHIFT without making a round-trip to the server. This call is optional as the server will return the same validation error, but we can offer a better user experience by performing this check on the client-side. The market requirements include the minimum time until invoice expiration, minimum invoice amount, and maximum invoice amount that will be accepted by REDSHIFT.

In our app, we make both calls at the same time as the page is created:

async created() {
  [this.markets, this.requirements] = await Promise.all([
    redshift.http.getMarkets(),
    redshift.http.getMarketRequirements(),
  ]);
}

Gathering & Validating User Input

Now that we have the markets and market requirements, we'll collect information from the user required to perform the swap.

At a minimum, we require the invoice that REDSHIFT will pay. If your application only supports one on-chain payment asset, ETH for example, then you will not need to collect the payment asset from the user.

We also support bitcoin payments in our app, so the user is required to select a payment asset.

To provide a better user experience, we'll validate the invoice on the client-side. To do so, we use bolt11-decoder, a lighter version of bolt11, to decode the invoice.

If the invoice does not decode successfully, then it is invalid:

/**
 * Validate the passed invoice. If valid, return the decoded invoice
 * @param invoice The bolt11 invoice
 */
isValidInvoice(invoice: string) {
  try {
    const decodedInvoice = decode(invoice);
    return {
      decodedInvoice,
      isValid: true,
    };
  } catch (error) {
    return {
      isValid: false,
    };
  }
}

Once the user has input a valid invoice and selected a market, we have enough information to check if the market requirements have been met.

We'll perform this check when the user clicks Pay Invoice. Alternatively, you could run this validation when the input or select change event fires.

You can see this call in action inside the initiateSwap method:

// Ensure the invoice meets the market requirements
const decodedInvoice = decode(data.invoice);
const invoiceMeetsRequirements = this.marketRequirementsSatisfied(
  decodedInvoice,
  data.market,
);
if (!invoiceMeetsRequirements) return;

If the invoice does not meet the market requirements, the error is set on the input and code execution is stopped.

Requesting a Quote

Once we've validated the information provided by the user, we're ready to request a quote from REDSHIFT.

This is a simple process that involves two steps; establish a WebSocket connection and request the quote:

// Establish a WebSocket connection
await redshift.ws.connect();

// Request the quote
const quote = await redshift.ws.requestQuote({
  invoice: data.invoice,
  market: data.market,
});

The quote response will look like this:

{ 
   "orderId":"56f970d4-24cc-4112-8e1a-4bef7becbee2",
   "expiryTimestampMs":1571943386485,
   "amount":"0.005068660000000000",
   "details":{ 
      "unsignedFundingTx":{ 
         "to":"0xd4589fB5b5ABB44e1A8cb95CfF0Ca9E0e78D9D5d",
         "data":"0x3fdcdd1e56f970d424cc41128e1a4bef7becbee20000000000000000000000000000000009495061c40a27c05ca574ff5c4d61869e4a936a003b13f8050d5aeba0ecfc7d",
         "value":"5068660000000000"
      }
   }
}

Payment

We now have everything that we need to request payment from the user. Move to the Payment page for this part of the tutorial.

To provide a good UX, we'll subscribe to order state updates and present them to the user.

You can subscribe to state updates using the following method:

await redshift.ws.subscribeToOrderState(this.orderId);

Once subscribed, we must attach an event handler that gets fired when the order state changes. In this sample, we'll feed the state update event to a method called handleStateChange that will update the state for display, increase the progress bar completion percentage, and populate the payment proof once complete:

redshift.ws.onOrderStateChanged(this.handleStateChange);

As you may have gathered from the above description, not all state updates share the same schema. There are three types of state updates.

Now that our state update listener is hooked up, we're ready to accept payment from the user.

In this example, all MetaMask interactions are handled through the metamask object. We'll skip over many of the actions required to connect and communicate with MetaMask as they are not specific to REDSHIFT.

When the user clicks the Send Payment button, we need to pass the unsigned funding transaction to MetaMask using the sendTransaction RPC call. This will pop up the MetaMask window so the user can sign the transaction.

In this example, we use the MetaMask provider to make the RPC call directly:

/**
 * Call eth_sendTransaction. Display an error message if
 * an error is thrown.
 * @param address The active address
 */
async sendTransaction(address: string) {
  try {
    const { data, to, value } = this.tx; // Tx values from REDSHIFT
    await metamask.sendTransaction({
      data,
      to,
      value: value ? decToHex(value as string) : undefined,
      from: address,
    });
  } catch (error) {
    this.metamaskError = error.message;
  }
}

Note that this code can be simplified by using a library like web3 or ethers.js.

Once signed, MetaMask will broadcast the transaction automatically. The order state update listener will take over from here. Upon invoice payment, the progress bar will be set to 100%, the proof of payment will be populated, and the Start Another Swap button will be visible.

Facilitating a Refund

NOTE: In a real application, the refund details should be provided to the user as a file download before they're allowed to fund the swap. This sample only demos the refund flow when navigating directly from a failed swap.

If REDSHIFT fails to pay the invoice, the user must be able to reclaim the funds that they sent to the swap contract.

Open the Refund page to view the sample refund flow.

In this example, the user is responsible for refund transaction submission. This is not strictly required. Any address is capable of signing and broadcasting the refund transaction. Regardless of who broadcasts this transaction, the funds will always be returned to the address that initially funded the swap. This could be used to submit the refund transaction on behalf of the user when the timelock expires, which offers a better UX.

We cannot allow the user to broadcast the refund transaction immediately following invoice payment failure. Any refund transaction mined before the block timelock is met will fail. The ether swap timelock is currently set to 480 blocks, which means that the user must wait roughly 2 hours before refund transaction submission.

To begin the process, we'll fetch the refund details using the order id of the failed swap:

this.refund.details = await redshift.ws.requestRefundDetails(this.orderId);

The ether refund details contain the following information:

If blocksRemaining is greater than 0 then we know that the refund transaction cannot be submitted yet. Instead, we'll display a block countdown to timelock expiration.

To accomplish this, we'll subscribe to the Ethereum block height using the REDSHIFT WebSocket API and update the UI when a new block is mined:

if (this.blocksUntilRefundable > 0) {
  const { network, subnet } = getNetworkDetails(this.refund.details.market);

  await redshift.ws.subscribeToBlockHeight(network, subnet);
  redshift.ws.onBlockHeightChanged(update =>
    this.handleBlockHeightChange(update, network, subnet),
  );
}

Once blocksUntilRefundable is less than or equal to 0, we can enable the Get Refund button and allow the user to submit the refund transaction.

From here, we use the same approach as the funding transaction. The refund transaction details are passed to the sendTransaction RPC call and the progess bar is updated using the order state subscription. Upon refund confirmation, the progress bar will be set to 100% and the Start Another Swap button will be visible.

API

HTTP API

Orders

Endpoints to interact with and retrieve orders.

Get Orders

GET https://api.redshift.radar.tech/api/orders

This endpoint allows you to get orders via the lightning invoice and payment asset. Because an actual invoice could potentially exceed the maximum URL length, we use the invoice hash.

Query Parameters

Name

Type

Description

Example

Get Order

GET https://api.redshift.radar.tech/api/orders/:id

Path Parameters

Example

Get Order State

GET https://api.redshift.radar.tech/api/orders/:id/state

Path Parameters

Example

Get Order Funding Details

GET https://api.redshift.radar.tech/api/orders/:id/fundDetails

Path Parameters

Example

Get Order Transactions

GET https://api.redshift.radar.tech/api/orders/:id/transactions

Path Parameters

Example

Get Refund

GET https://api.redshift.radar.tech/api/orders/:id/refund

Path Parameters

Example

Market

Endpoints to retrieve market requirements.

Get Markets

GET https://api.redshift.radar.tech/api/markets

This endpoint allows you view available markets

Example

Get Requirements for All Markets

GET https://api.redshift.radar.tech/api/markets/requirements

Example

Get Requirements for Market

GET https://api.redshift.radar.tech/api/markets/:market/requirements

Path Parameters

Example

WebSocket API

Introduction

Our WebSocket API uses . You must use a socket.io client to interact with the Redshift WebSocket API.

If you are building a JavaScript or TypeScript application, we have a that does a lot of the heavy lifting for WebSockets.

Client Example

JavaScript Example

Other Language Clients:

Events

Websocket information to communicate with REDSHIFT.

Messages:

requestQuote

Use this endpoint to request a quote to exchange an on-chain asset for Lightning Bitcoin (LBTC). Available markets are in docs.

// Request
{
    market: Market;
    invoice: string;
    refundAddress?: string;
}

// Bitcoin Response
{
    success: boolean,
    message: {
        orderId: string;
        expiryTimestampMs: number;
        amount: string;
        details: {
            payToAddress: string;
            redeemScript: string;
            refundableAtBlockHeight: number;
        }
    }
}


// Ethereum Response
{
    success: boolean,
    message: {
        orderId: string,
        expiryTimestampMs: number,
        amount: string,
        details: {
          unsignedFundingTx: string,
        }
    }
}

import io from 'socket.io-client';

const socket = io.connect("https://api.redshift.radar.tech/user/v1");

const request = {
  market: "BTC_LBTC";
  invoice: "lnbc1m1p0pv6fepp5kjf5zgm6590w77u3qtg38cjwxwz36l505q3gurl4nl8xw47t33msdqsgdf4wfmnyp9k27tncqzpgwrdthp4apgu7v4s53xc27clm82nkchmylm5huvwdd660q36e82vske04eeesljjyt89q3aglzr9l7l3yxpy5pwfl08unztfrqhcndesqyym288";
  refundAddress: "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa";
}

socket.emit(
  "requestQuote",
  request,
  ({ success, message }: WebSocketResponse<Quote | string>) => {
    if (success) {
      console.log(message)
      // {
      //   orderId: "13283979-2c0b-45e4-b2e0-2a487535822e";
      //   expiryTimestampMs: 1578598212267;
      //   amount: "0.001056000000000000";
      //   details: {
      //     payToAddress: "3LKomc2i3rLm2TnA36U4pGH25cFWvRMnJB";
      //     redeemScript: "76a914d5846ccb08521347c1d5718ec460656d67427cbf8763752102369b4d174f601239daef6a83bf553092e139901e6ed19ffbcbedcee07be7a4ae6703575709b17576a914c1e27ac884310271f04dd1ebe9eb4e135113a1d08868ac";
      //     refundableAtBlockHeight: 612183;
      //   }
      // }
    }
    return reject(new Error(message));
  },
);

subscribeToOrderState

Use this endpoint to subscribe to an order's state. If an order's state changes, subscribers will be sent a message with the new state of the order. This may be useful to notify users how their order is progressing.

// Request
{
    orderId: string
}

// Response
{  
    success: boolean 
}

import io from 'socket.io-client';

const socket = io.connect("https://api.redshift.radar.tech/user/v1");

const request = {
  orderId: "13283979-2c0b-45e4-b2e0-2a487535822e"
}

socket.emit(
  "subscribeToOrderState",
  request,
  ({ success, message }: WebSocketResponse<Quote | string>) => {
    if (success) {
      return resolve("Subscribed!");
    }
    return reject(new Error(message));
  },
);

unsubscribeFromOrderState

Use this endpoint to unsubscribe from an order's state. If an order's state changes in the future, the client will not be notified.

// Request
{
    orderId: string
}

// Response
{  
    success: boolean 
}

import io from 'socket.io-client';

const socket = io.connect("https://api.redshift.radar.tech/user/v1");

const request = {
  orderId: "13283979-2c0b-45e4-b2e0-2a487535822e"
}

socket.emit(
  "unsubscribeFromOrderState",
  request,
  ({ success, message }: WebSocketResponse<Quote | string>) => {
    if (success) {
      return resolve("Unsubscribed!");
    }
    return reject(new Error(message));
  },
);

subscribeToBlockHeight

Use this endpoint to subscribe to a blockchain's current block height. If the blockchain's current block height changes, subscribers will be sent a message with the new block height. This might be useful to notify users whether they can refund their transaction.

Valid Networks:

bitcoin
ethereum

Valid Subnets:

Bitcoin:

simnet
testnet
mainnet

Ethereum:

ganache_simnet
kovan_testnet
mainnet

// Request
{
    network: Network;
    subnet: Subnet;
}

// Response
{  
    success: boolean 
}

import io from 'socket.io-client';

const socket = io.connect("https://api.redshift.radar.tech/user/v1");

const request = {
  network: "bitcoin";
  subnet: "mainnet";
}

socket.emit(
  "subscribeToBlockHeight",
  request,
  ({ success, message }: WebSocketResponse<Quote | string>) => {
    if (success) {
      return resolve("Subscribed!");
    }
    return reject(new Error(message));
  },
);

unsubscribeFromBlockHeight

Use this endpoint to unsubscribe from a blockchain's current block height. If the blockchain's current block height changes in the future, the client will not be notified.

Valid Networks:

bitcoin
ethereum

Valid Subnets:

Bitcoin:

simnet
testnet
mainnet

Ethereum:

ganache_simnet
kovan_testnet
mainnet

// Request
{
    network: Network;
    subnet: Subnet;
}

// Response
{  
    success: boolean 
}

import io from 'socket.io-client';

const socket = io.connect("https://api.redshift.radar.tech/user/v1");

const request = {
  network: "bitcoin";
  subnet: "mainnet";
}

socket.emit(
  "unsubscribeToBlockHeight",
  request,
  ({ success, message }: WebSocketResponse<Quote | string>) => {
    if (success) {
      return resolve("Subscribed!");
    }
    return reject(new Error(message));
  },
);

requestRefundDetails

Use this endpoint to request the refund details for a particular order. This information can also be retrieved using the requestRefundDetails HTTP endpoint, but it may make more sense to use an already established WebSocket connection depending on your application.

// Request
{
    orderId: string
}

// Bitcoin Response
{
    success: boolean,
    message: {
        market: Market;
        state: UserSwapState;
        blocksRemaining: number | undefined;
        refundableAtBlockHeight: number | undefined;
        refundableBalance: string;
        details: {
            refundAddress: string;
            redeemScript: string;
            currentBlockHeight: number;
            feeTokensPerVirtualByte: number;
            utxos: TxOutput[];
        }
    }
}


// Ethereum Response
{
    success: boolean,
    message: {
        market: Market;
        state: UserSwapState;
        blocksRemaining: number | undefined;
        refundableAtBlockHeight: number | undefined;
        refundableBalance: string;
        details: {
            to: string;
            data: string;
        }
    }
}

import io from 'socket.io-client';

const socket = io.connect("https://api.redshift.radar.tech/user/v1");

const request = {
  orderId: "13283979-2c0b-45e4-b2e0-2a487535822e";
}

socket.emit(
  "requestRefundDetails",
  request,
  ({ success, message }: WebSocketResponse<Quote | string>) => {
    if (success) {
      console.log(message)
        // {
        //   market: "BTC_LBTC";
        //   state: "Completed";
        //   blocksRemaining: 0;
        //   refundableAtBlockHeight: 607878;
        //   refundableBalance: "0.0005263";
        //   details: {
        //     refundAddress: "bc1q50qmmgf3mtp95qesqq27h8gsdx9syuzv9p8qfa";
        //     redeemScript: "76a9148ec7c524f0cfca47daaa56827c76d94e0ea47c2c8763752103698deb28d5807611b0545b2c0b59ea4ae84393b2e22b7f131f1b89694b43749a6703864609b17576a914a3c1bda131dac25a03300015eb9d10698b02704c8868ac";
        //     currentBlockHeight: 612073;
        //     feeTokensPerVirtualByte: 30;
        //     utxos: [
        //       {
        //         "txId": "d2a153c4024152a06cb1ee6e5da1fac3548085ed77dc75f438586c37fed26678",
        //         "index": 1,
        //         "tokens": 52630
        //       }
        //     ];
        //   }
        // }
        
    }
    return reject(new Error(message));
  },
);

broadcastTransaction

Use this endpoint broadcasts a signed transaction to the specific network. This can be used to broadcast refund transactions directly from your app without needing to run a node.

Valid onchainTickers are defined in the docs.

// Request
{
    onchainTicker: OnChainTicker;
    signedTxHex: string;
}

// Response
{
    success: boolean,
    message: {
        txId: "d2a153c4024152a06cb1ee6e5da1fac3548085ed77dc75f438586c37fed26678"
    }
}

import io from 'socket.io-client';

const socket = io.connect("https://api.redshift.radar.tech/user/v1");

const request = {
  onchainTicker: "BTC",
  signedTxHex: "8adb7454fe7d8d0f55ee89c592926d6f6f032207020e4ad56ff7ca3c80cbe26e"
}

socket.emit(
  "broadcastTransaction",
  request,
  ({ success, message }: WebSocketResponse<Quote | string>) => {
    if (success) {
      console.log(message)
        // {
        //   txId: "d2a153c4024152a06cb1ee6e5da1fac3548085ed77dc75f438586c37fed26678",
        // }
        
    }
    return reject(new Error(message));
  },
);

requestMarketRequirements

Use this endpoint to get the market requirements.

N/A

// Response
{
    market: Market;
    payReq: {
        minExpirationSeconds: string;
        minBaseUnits: string;
        maxBaseUnits: string;
    }
}

import io from 'socket.io-client';

const socket = io.connect("https://api.redshift.radar.tech/user/v1");

const request = { }

socket.emit(
  "requestMarketRequirements",
  request,
  ({ success, message }: WebSocketResponse<Quote | string>) => {
    if (success) {
      console.log(message)
        // {
        //   market: "BTC_LBTC";
        //   payReq:{
        //     minExpirationSeconds:"2400",
        //     minBaseUnits:"30000",
        //     maxBaseUnits:"1000000"
        //   }
        // }
        
    }
    return reject(new Error(message));
  },
);

Libraries

@radar/redshift-api-client

REDSHIFT HTTP & WebSocket Client Library

View on Github

Installation

npm

npm install @radar/redshift-api-client

yarn

yarn add @radar/redshift-api-client

Usage - REDSHIFT Client

The REDSHIFT client acts as a wrapper for the HTTP & WebSocket clients.

Import

import { RedshiftClient } from '@radar/redshift-api-client';

Instantiation

Mainnet

By default, the REDSHIFT client targets mainnet

const client = new RedshiftClient();

If you prefer to be explicit, you can pass RedshiftApiUrl.MAINNET into the constructor

const client = new RedshiftClient(RedshiftApiUrl.MAINNET);

Testnet

const client = new RedshiftClient(RedshiftApiUrl.TESTNET);

Client Access

The http and ws getters can be used to access the HTTP & WebSocket client methods.

http - Get Markets Example

Get the active markets

const markets = await client.http.getMarkets();

ws - Connect Example

Establish a connection to the REDSHIFT WebSocket API

await client.ws.connect();

Usage - HTTP Client

The HTTP client can be used to interact with the REDSHIFT HTTP endpoints.

Import

import { HttpClient } from '@radar/redshift-api-client';

Instantiation

Mainnet

By default, the HTTP client targets mainnet

const client = new HttpClient();

If you prefer to be explicit, you can pass RedshiftApiUrl.MAINNET into the constructor

const client = new HttpClient(RedshiftApiUrl.MAINNET);

Testnet

const client = new HttpClient(RedshiftApiUrl.TESTNET);

Methods

Get Markets

Get the active markets

const markets = await client.getMarkets();

Get Orders

Get all swap orders for a specific invoice

const orders = await client.getOrders(invoice);

// Or filter by the on-chain asset used to fund the swap
const orders = await client.getOrders(invoice, OnChainTicker.ETH);

Get Order

Get a single swap order

const order = await client.getOrder(orderId);

Get Order State

Get the state of a single order

const state = await client.getOrderState(orderId);

Get Order Fund Details

Get the fund details for an order

const state = await client.getOrderFundDetails(orderId);

Get Order Transactions

Get the transactions relating to an order

const state = await client.getOrderTransactions(orderId);

Get Order Refund Details

Get the refund details for a single order

const details = await client.getOrderRefundDetails(orderId);

Usage - WebSocket Client

The WebSocket client can be used to interact with the REDSHIFT WebSocket endpoints. Many WebSocket interactions are promisified to provide a better developer experience.

Import

import { WebSocketClient } from '@radar/redshift-api-client';

Instantiation

Mainnet

By default, the WebSocket client targets mainnet

const client = new WebSocketClient();

If you prefer to be explicit, you can pass RedshiftApiUrl.MAINNET into the constructor

const client = new WebSocketClient(RedshiftApiUrl.MAINNET);

Testnet

const client = new WebSocketClient(RedshiftApiUrl.TESTNET);

Methods

Connect

Establish a connection to the REDSHIFT WebSocket API

await client.connect();

Disconnect

Disconnect from the REDSHIFT WebSocket API

client.disconnect();

Request Quote

Request a quote for the provided invoice and selected on-chain asset

await client.requestQuote(quoteRequest);

Subscribe to Order State

Subscribe to order state updates for the provided order id

await client.subscribeToOrderState(orderId);

On Order State Changed

Execute the callback function when an order state update is received

client.onOrderStateChanged(stateUpdate => {
  console.log(stateUpdate);
});

Unsubscribe from Order State

Unsubscribe from order state updates for the provided order id

await client.unsubscribeFromOrderState(orderId);

Subscribe to Block Height

Subscribe to block height updates for the provided network and subnet

await client.subscribeToBlockHeight(network, subnet);

On Block Height Changed

Execute the callback function when a block height update is received

client.onBlockHeightChanged(blockHeightUpdate => {
  console.log(blockHeightUpdate);
});

Unsubscribe from Block Height

Unsubscribe from block height updates for the provided network and subnet

await client.unsubscribeFromBlockHeight(network, subnet);

Request Refund Details

Request refund details for a specific swap order

const details = await client.requestRefundDetails(orderId);

Broadcast Transaction

Broadcast signed transaction hex to your network of choice

const { txId } = await client.broadcastTransaction(txRequest);

@radar/lnrpc

A Typescript gRPC client for LND with support for all LND sub-servers.

View on Github

Originally forked from Matt-Jensen/lnrpc.

Features

Auto-generates lnd/lnrpc clients and Typescript type definitions using a target release tag
Supports all LND sub-servers
Wraps requests in promises
Easily setup SSL and Macaroons
Instantiates all gRPC services
uint64/int64 types cast to string to prevent precision loss

Installation

npm install @radar/lnrpc
# OR
yarn add @radar/lnrpc

Notes:

Ensure you have an lnd instance running with --no-macaroons, unless you provide macaroon authentication to your lnrpc instance when created.
If you want to interact with the LND sub-servers, ensure that LND was compiled with the necessary sub-server build tags.

If the following error is thrown in the consuming application, run npm rebuild:

Error: Failed to load gRPC binary module because it was not installed for the current system

Usage

This package exports a create function for the main gRPC server as well as each sub-server:

import {
  createAutopilotRpc,
  createChainRpc,
  createInvoicesRpc,
  createLnRpc,
  createRouterRpc,
  createSignRpc,
  createWalletRpc,
  createWatchtowerRpc,
  createWtClientRpc,
} from '@radar/lnrpc';

You can also import the create function for the main gRPC server using the default import:

import createLnRpc from '@radar/lnrpc';

If you want to interact with all servers, wrap the functions in a class or object for easy initialization:

import createLnRpc, {
  AutopilotRpc,
  ChainRpc,
  createAutopilotRpc,
  createChainRpc,
  createInvoicesRpc,
  createRouterRpc,
  createSignRpc,
  createWalletRpc,
  createWatchtowerRpc,
  createWtClientRpc,
  InvoicesRpc,
  LnRpc,
  RouterRpc,
  RpcClientConfig,
  SignRpc,
  WalletRpc,
  WatchtowerRpc,
  WtClientRpc,
} from '@radar/lnrpc';

export class Lightning {
  public static lnrpc: LnRpc;
  public static autopilotrpc: AutopilotRpc;
  public static chainrpc: ChainRpc;
  public static invoicesrpc: InvoicesRpc;
  public static routerrpc: RouterRpc;
  public static signrpc: SignRpc;
  public static walletrpc: WalletRpc;
  public static watchtowerrpc: WatchtowerRpc;
  public static wtclientrpc: WtClientRpc;

  /**
   * Initialize gRPC clients for the main server and all sub-servers
   * @param config The RPC client connection configuration
   */
  public static async init(config: RpcClientConfig): Promise<void> {
    this.lnrpc = await createLnRpc(config);
    this.autopilotrpc = await createAutopilotRpc(config);
    this.chainrpc = await createChainRpc(config);
    this.invoicesrpc = await createInvoicesRpc(config);
    this.routerrpc = await createRouterRpc(config);
    this.signrpc = await createSignRpc(config);
    this.walletrpc = await createWalletRpc(config);
    this.watchtowerrpc = await createWatchtowerRpc(config);
    this.wtclientrpc = await createWtClientRpc(config);
  }
}

Usage Example - Main Server

Connecting to an lnd instance at localhost:10001.

import createLnRpc from '@radar/lnrpc';

(async () => {
  const lnRpcClient = await createLnRpc(config);

  // All requests are promisified and typed
  const { confirmedBalance } = await lnRpcClient.walletBalance();

  // ...and you're off!
  console.log(confirmedBalance);

  // subscribe to LND server events
  const subscriber = await lnRpcClient.subscribeInvoices();
  subscriber.on('data', invoice => {
    console.log(invoice); // do something with invoice event
  });
})();

Options Example - Main Server

import createLnRpc from '@radar/lnrpc';

(async () => {
  const lnRpcClient = await createLnRpc({
    /*
     * By default lnrpc connects to `localhost:10001`,
     * however we can point to any host.
     */
    server: '173.239.209.2:3001',

    /*
     * By default  lnrpc looks for your tls certificate at:
     * `~/.lnd/tls.cert`, unless it detects you're using macOS and
     * defaults to `~/Library/Application\ Support/Lnd/tls.cert`
     * however you can configure your own SSL certificate path like:
     */
    tls: './path/to/tls.cert',

    /*
     * You can also provide a TLS certificate directly as a string
     * (Just make sure you don't commit this to git).
     * Overwrites: `tls`
     */
    cert: process.env.MY_SSL_CERT,

    /*
     * Optional path to configure macaroon authentication
     * from LND generated macaroon file.
     */
    macaroonPath: './path/to/data/admin.macaroon',

    /*
     * Optional way to configure macaroon authentication by
     * passing a hex encoded string of your macaroon file.
     * Encoding: `xxd -ps -u -c 1000 ./path/to/data/admin.macaroon`
     * Details: https://github.com/lightningnetwork/lnd/blob/dc3db4b/docs/macaroons.md#using-macaroons-with-grpc-clients
     */
    macaroon: process.env.MY_MACAROON_HEX,
  });

  try {
    const getInfoResponse = await lnRpcClient.getInfo();
    console.log(getInfoResponse);
  } catch (error) {
    console.error(error);
  }
})();

API Reference

All main server (lnrpc) methods documentation can be found here.

Usage With BTCPayServer

By default lnrpc assumes SSl certificate pinning. In order to use lnrpc with a service (like BTCPayServer) which manages your certification, you'll have to opt to disable certificate pinning by passing { tls: false } within your lnrpc configuration.

Contributing

Clone Repository & Install Dependencies

git clone git@github.com:RadarTech/lnrpc.git && cd $_

npm install
# OR
yarn

Change LND gRPC release version

To change the gRPC definitions used for all auto-generated types and RPC methods edit the config.lnd_release_tag value in package.json to the desired LND release tag and run the following:

npm run update-protos
# OR
yarn update-protos

# AND

npm run generate
# OR
yarn generate

Newly generated type definitions will be available in ./generated. You can now delete the old proto file inside the lnd directory. Use the generated type definitions to update the types in src/types/rpc.

License

This project is licensed under the MIT License.

@radar/htlc

A library used to construct and interact with HTLCs across multiple networks & network models

View on Github

Installation

npm

npm install @radar/htlc

yarn

yarn add @radar/htlc

Usage - Bitcoin

Construct a Bitcoin HTLC

Construct a new Bitcoin HTLC with an absolute timelock:

import { HTLC, UTXO } from '@radar/htlc';

const htlc = HTLC.construct(Network.BITCOIN, BitcoinSubnet.SIMNET, {
  paymentHash: 'fba6da3ff596b9c6fabe67d4f728474697640ef6edd9e361c2a46be345112839',
  claimerPublicKey: '0286ab3b59ce3862515b01c8a282edb6011b4eb50c608ab298bfd70f6033f7bc65',
  refundAddress: 'sb1qxnqqm56ta40p3uhtsmtdxglhwuxjk3tul94mq0',
  timelock: {
    type: UTXO.LockType.ABSOLUTE,
    blockHeight: 597732,
  },
});

Construct a new Bitcoin HTLC with a relative timelock:

import { HTLC, UTXO } from '@radar/htlc';

const htlc = HTLC.construct(Network.BITCOIN, BitcoinSubnet.SIMNET, {
  paymentHash: 'fba6da3ff596b9c6fabe67d4f728474697640ef6edd9e361c2a46be345112839',
  claimerPublicKey: '0286ab3b59ce3862515b01c8a282edb6011b4eb50c608ab298bfd70f6033f7bc65',
  refundAddress: 'sb1qxnqqm56ta40p3uhtsmtdxglhwuxjk3tul94mq0',
  timelock: {
    type: UTXO.LockType.RELATIVE,
    blockBuffer: 50,
  },
});

Construct a Bitcoin HTLC from an existing redeem script:

import { HTLC } from '@radar/htlc';

const htlc = HTLC.construct(
  Network.BITCOIN,
  BitcoinSubnet.SIMNET,
  '76a914c15949a2e2a414b5c641f32c4c2ee07be644e165876375210398c9a44bed9f59c6041a574602aab0af6a08f3f0fb847fd9a167f7afd71b8d25670114b27576a9143f1857b3db895b4d481a46e5a0129cb2b04781c88868ac',
);

Construct a Bitcoin HTLC with a refund public key instead of address:

import { HTLC, UTXO } from '@radar/htlc';

const htlc = HTLC.construct(Network.BITCOIN, BitcoinSubnet.SIMNET, {
  paymentHash: 'fba6da3ff596b9c6fabe67d4f728474697640ef6edd9e361c2a46be345112839',
  claimerPublicKey: '0286ab3b59ce3862515b01c8a282edb6011b4eb50c608ab298bfd70f6033f7bc65',
  refundPublicKey: '029814897bbfe085fcf1611a7100919f31b4424443d694a52b86bbb9ab9447d073',
  timelock: {
    type: UTXO.LockType.RELATIVE,
    blockBuffer: 50,
  },
});

Interact with the Bitcoin HTLC

Get the HTLC details:

const { details } = htlc;

Get the redeem script:

const { redeemScript } = htlc;

Generate the fund transaction. You can now broadcast it using sendrawtransaction:

const fundTxHex = htlc.fund(utxos, fundingAmount, privateKey);

Generate the claim transaction. You can now broadcast it using sendrawtransaction:

const claimTxHex = htlc.claim(
  utxos,
  destinationAddress,
  currentBlockHeight,
  feeTokensPerVirtualByte,
  paymentSecret,
  privateKey,
);

Generate the refund transaction. You can now broadcast it using sendrawtransaction:

const refundTxHex = htlc.refund(
  utxos,
  destinationAddress,
  currentBlockHeight,
  feeTokensPerVirtualByte,
  privateKey,
);

For working examples, view the Absolute or Relative Timelock Bitcoin HTLC tests.

Usage - Ethereum

Construct an Ethereum HTLC

Asset: Ether

import { HTLC } from '@radar/htlc';

const htlc = HTLC.construct(Network.ETHEREUM, EthereumSubnet.GANACHE_SIMNET, {
  orderUUID,
  provider: web3.currentProvider,
  assetType: EVM.AssetType.ETHER,
});

Asset: ERC20

import { HTLC } from '@radar/htlc';

const htlc = HTLC.construct(Network.ETHEREUM, EthereumSubnet.GANACHE_SIMNET, {
  orderUUID,
  provider: web3.currentProvider,
  tokenContractAddress,
  assetType: EVM.AssetType.ERC20,
});

Interact with the Ethereum HTLC

Get the deployed HTLC contract instance:

const { contract } = htlc;

Generate, sign, and broadcast the fund transaction using the passed provider:

const txReceipt = await htlc.fund(amount, paymentHash);

Generate and broadcast the claim transaction using the passed provider:

const txReceipt = await htlc.claim(paymentSecret);

Generate and broadcast the refund transaction using the passed provider:

const txReceipt = await htlc.refund();

Want to pass in additional tx params? Pass all desired tx params as the last argument:

const txReceipt = await htlc.refund(true, {
  gas: 200000,
});

Don't want to sign and broadcast the transaction? Set shouldBroadcast to false to return the unsigned transaction. You can now broadcast it using eth_sendTransaction:

const unsignedTx = await htlc.refund(false);

For working examples, view the Ether or ERC20 Ethereum HTLC tests.

Usage - Stellar

Construct a Stellar HTLC

import { HTLC } from '@radar/htlc';

const htlc = HTLC.construct(Network.STELLAR, StellarSubnet.TESTNET, {
  secret: 'SCHMRGINH4CDPUPKBEQZTFZHNRSZKC3NYEFMSUYNDKA4OQK3ZA7JT7C6',
});

Interact with the Stellar HTLC

Build, sign, and broadcast a transaction (envelope) to create an escrow account (escrowPubKey):

await htlc.create();

Build the fundEnvelope and refundEnvelope for the user:

const fundEnvelope = await htlc.fund(
  userPubKey,
  fundAmount,
  paymentHash,
);

const refundEnvelope = await htlc.refund(
  userPubKey,
  timelockInSeconds,
);

Once the user funds, pay the invoice to get the payment secret. Use the payment secret to claim the funds. Once broadcast, the escrow account gets merged into the server account. Swap Complete.

await htlc.claim(paymentSecret);

For a working example, view the Stellar HTLC tests.

Testing

Build container services for tests

docker-compose up -d

Run tests:

yarn test

Additional Information

Subnet Naming

Subnets should be named SIMNET, TESTNET, or MAINNET if there is only one instance of the subnet type. If there are two or more instances of a single subnet type (multiple testnets, etc.) then the naming convention should be SUBNETNAME_SUBNETTYPE. e.g. KOVAN_TESTNET.

@radar/redshift-types

Common types used across REDSHIFT codebases

Installation

npm

yarn

Usage

Update typeRoots in tsconfig.json for declarations access:

@radar/redshift-utils

Utilities used across REDSHIFT codebases

View on Github

Installation

npm

npm install @radar/redshift-utils

yarn

yarn add @radar/redshift-utils

Usage - Validator

Import

import { validator } from '@radar/redshift-utils';

Methods

Validate Network

Determine if the passed network is valid

const isValid = await validator.isValidNetwork(network);

Validate On-Chain Ticker

Determine if the passed on-chain ticker is valid

const isValid = await validator.isValidOnchainTicker(ticker);

Validate Market

Determine if the passed market is valid

const isValid = await validator.isValidMarket(market);

Validate UUID

Determine if the passed UUID is valid

const isValid = await validator.isValidUUID(uuid);

Validate Base58Check

Determine if the passed string is valid base58check

const isValid = await validator.isValidBase58Check(s);

Validate Bech32

Determine if the passed string is valid bech32

const isValid = await validator.isValidBech32(s);

Validate Base58Check or Bech32

Determine if the passed string is valid base58check or bech32

const isValid = await validator.isValidBase58CheckOrBech32(s);

Validate Hex

Determine if the passed string is a valid hex

const isValid = await validator.isValidHex(s);

Validate Network & Subnet

Determine if the passed network and subnet are valid

const isValid = await validator.isValidNetworkAndSubnet(network, subnet);

Ether Swap Tutorial

In this tutorial, we'll integrate the REDSHIFT Javascript SDK into a Vue frontend that can be used to execute a Kovan Testnet Ether (kETH) <-> Lightning Testnet Bitcoin (ltBTC) submarine swap.

Prerequisites

Install MetaMask

Clone this repository

git clone https://github.com/RadarTech/redshift-monorepo.git

Navigate to the sample project directory

cd redshift-monorepo/samples/sdk-usage-vue

Install dependencies

yarn

Run the application

yarn start

Facilitating a Swap

Overview

Fetch Initial Information

We'll begin by taking a look at the Start page.

First, we must fetch two important pieces of information from REDSHIFT: The active markets and market requirements.

The markets are rather self-explanatory. They tell us which markets REDSHIFT is currently servicing.

In our app, we make both calls at the same time as the page is created:

async created() {
  [this.markets, this.requirements] = await Promise.all([
    redshift.http.getMarkets(),
    redshift.http.getMarketRequirements(),
  ]);
}

Gathering & Validating User Input

Now that we have the markets and market requirements, we'll collect information from the user required to perform the swap.

We also support bitcoin payments in our app, so the user is required to select a payment asset.

To provide a better user experience, we'll validate the invoice on the client-side. To do so, we use bolt11-decoder, a lighter version of bolt11, to decode the invoice.

If the invoice does not decode successfully, then it is invalid:

/**
 * Validate the passed invoice. If valid, return the decoded invoice
 * @param invoice The bolt11 invoice
 */
isValidInvoice(invoice: string) {
  try {
    const decodedInvoice = decode(invoice);
    return {
      decodedInvoice,
      isValid: true,
    };
  } catch (error) {
    return {
      isValid: false,
    };
  }
}

Once the user has input a valid invoice and selected a market, we have enough information to check if the market requirements have been met.

We'll perform this check when the user clicks Pay Invoice. Alternatively, you could run this validation when the input or select change event fires.

You can see this call in action inside the initiateSwap method:

// Ensure the invoice meets the market requirements
const decodedInvoice = decode(data.invoice);
const invoiceMeetsRequirements = this.marketRequirementsSatisfied(
  decodedInvoice,
  data.market,
);
if (!invoiceMeetsRequirements) return;

If the invoice does not meet the market requirements, the error is set on the input and code execution is stopped.

Requesting a Quote

Once we've validated the information provided by the user, we're ready to request a quote from REDSHIFT.

This is a simple process that involves two steps; establish a WebSocket connection and request the quote:

// Establish a WebSocket connection
await redshift.ws.connect();

// Request the quote
const quote = await redshift.ws.requestQuote({
  invoice: data.invoice,
  market: data.market,
});

The quote response will look like this:

{ 
   "orderId":"56f970d4-24cc-4112-8e1a-4bef7becbee2",
   "expiryTimestampMs":1571943386485,
   "amount":"0.005068660000000000",
   "details":{ 
      "unsignedFundingTx":{ 
         "to":"0xd4589fB5b5ABB44e1A8cb95CfF0Ca9E0e78D9D5d",
         "data":"0x3fdcdd1e56f970d424cc41128e1a4bef7becbee20000000000000000000000000000000009495061c40a27c05ca574ff5c4d61869e4a936a003b13f8050d5aeba0ecfc7d",
         "value":"5068660000000000"
      }
   }
}

Payment

We now have everything that we need to request payment from the user. Move to the Payment page for this part of the tutorial.

To provide a good UX, we'll subscribe to order state updates and present them to the user.

You can subscribe to state updates using the following method:

await redshift.ws.subscribeToOrderState(this.orderId);

redshift.ws.onOrderStateChanged(this.handleStateChange);

As you may have gathered from the above description, not all state updates share the same schema. There are three types of state updates.

Now that our state update listener is hooked up, we're ready to accept payment from the user.

In this example, we use the MetaMask provider to make the RPC call directly:

/**
 * Call eth_sendTransaction. Display an error message if
 * an error is thrown.
 * @param address The active address
 */
async sendTransaction(address: string) {
  try {
    const { data, to, value } = this.tx; // Tx values from REDSHIFT
    await metamask.sendTransaction({
      data,
      to,
      value: value ? decToHex(value as string) : undefined,
      from: address,
    });
  } catch (error) {
    this.metamaskError = error.message;
  }
}

Note that this code can be simplified by using a library like web3 or ethers.js.

Facilitating a Refund

If REDSHIFT fails to pay the invoice, the user must be able to reclaim the funds that they sent to the swap contract.

Open the Refund page to view the sample refund flow.

To begin the process, we'll fetch the refund details using the order id of the failed swap:

this.refund.details = await redshift.ws.requestRefundDetails(this.orderId);

The ether refund details contain the following information:

If blocksRemaining is greater than 0 then we know that the refund transaction cannot be submitted yet. Instead, we'll display a block countdown to timelock expiration.

To accomplish this, we'll subscribe to the Ethereum block height using the REDSHIFT WebSocket API and update the UI when a new block is mined:

if (this.blocksUntilRefundable > 0) {
  const { network, subnet } = getNetworkDetails(this.refund.details.market);

  await redshift.ws.subscribeToBlockHeight(network, subnet);
  redshift.ws.onBlockHeightChanged(update =>
    this.handleBlockHeightChange(update, network, subnet),
  );
}

Once blocksUntilRefundable is less than or equal to 0, we can enable the Get Refund button and allow the user to submit the refund transaction.

REDSHIFT API Documentation

Welcome to the REDSHIFT API

What is REDSHIFT?

Why is this useful?

How does it work?

Routing Node Example Workflow

Merchant / Consumer Example Workflow

Getting Started

Definitions

Foundational Definitions

Asset & Market Abbreviations

Asset Abbreviations

onChainTickers

offChainTickers

Market Abbreviations

Testnet Market Abbreviations

Simnet Market Abbreviations

Order States

Funding

Refund

Other States

Errors

Order Errors

Market Errors

Invoice Errors

Broadcast Transaction

Other Errors

Tutorials

Ether Swap Tutorial

Prerequisites

Install MetaMask

Clone this repository

Navigate to the sample project directory

Install dependencies

Run the application

Facilitating a Swap

Overview

Fetch Initial Information

Gathering & Validating User Input

Requesting a Quote

Payment

Facilitating a Refund

API

HTTP API

Orders

Get Orders

Query Parameters

Example

​Get Order

Path Parameters

Example

Get Order State

Path Parameters

Example

​Get Order Funding Details

Path Parameters

Example

Get Order Transactions

Path Parameters

Example

Get Refund

Path Parameters

Example

Market

Get Markets

Example

Get Requirements for All Markets

Example

Get Requirements for Market

Path Parameters

Example

WebSocket API

Introduction

Client Example

JavaScript Example

Other Language Clients:

Events

Messages:

requestQuote

subscribeToOrderState

Get Order

Get Order Funding Details