Sparkswap Docs
  • Home
  • GitHub
  • Discord
  • Request Private Beta Invite

›Advanced Concepts

Getting Started

  • What is Sparkswap?
  • Installation
  • First Use
  • Hosting on the Cloud
  • Controlling a Remote Broker
  • Migrating sparkswapd from 0.1.x to 0.2.0
  • Migrating your Broker from 0.2.x/0.3.x to 0.4.x

Integration

  • Create a Client for the Broker
  • RPC API Reference
  • Using CCXT API

Order Mechanics

  • Order Types
  • Transaction Costs
  • Settlement
  • Order matching and priority
  • Partial Fills

Advanced Concepts

  • Swaps on Sparkswap
  • Communication with the Relayer
  • Trade Lifecycle
  • Common Market Issues
  • Interchain Router
  • Recovering Funds
  • Using Your Pre-existing Blockchain Node

Communication with the Relayer

The Sparkswap Relayer is a central service for coordinating and publishing actions of the market participants. It is operated by Sparkswap the company. It is primarily a dumb service to push order information from those posting it to those listening for it, but it also provides a few mechanisms to:

  1. Prevent fraud and market manipulation
  2. Collect fees from market participants
  3. Maximize smooth execution

Responsibilities of the Relayer

To meet these objectives, the Relayer has five specific responsibilities:

  1. Taking order deposits
  2. Collecting order fees
  3. Verifying reachability of counterparties
  4. Cancelling orders on Maker disconnect
  5. Opening alt chain channels to participants

Order Deposits

In order to place orders on the Relayer and Fill orders on the Relayer, Brokers are required to pay deposits via the Lightning Network which are held by the Relayer until one of the following is true:

For Order Deposits:

  1. The Order is rejected
  2. The Order is cancelled
  3. The Fill has been executed and preimage redeemed by the Maker

For Fill Deposits:

  1. The Fill is rejected
  2. The Fill has been executed and preimage redeemed by the Maker

The Relayer requires a deposit for Makers to ensure that the order place is a genuine indication of interest. Without the deposit, Makers could place orders that they never intend to fill, and thereby attempt to manipulate market prices (i.e. spoofing). With the deposit in place, if they do not execute a filled swap they are economically penalized.

The Relayer requires a deposit for Takers to ensure that Fills are binding. Without the deposit, Takers could send Fills, removing orders from the orderbook without actually executing the trade, thereby attempting to manipulate market prices (i.e. spoofing). With the deposit in place, if they do not execute the fill they are economically penalized.

The deposit for both parties is released only when the Maker reveals the preimage associated with the swap hash provided by the Taker. It is impossible for the Maker to determine the value of the preimage without completing the swap (or colluding with the Taker). It is proof positive to the Relayer that the swap has completed. It is possible, but difficult for the Maker and Taker to collude and redeem preimages for deposits without completing the swap. See Common issues with exchanges and how this design handles them for more information.

Order Fees

The Relayer charges fees to both participants in the swap. This is to compensate the Relayer for performing its duty of coordinating action between Makers and Takers and broadcasting Market information.

Fees are paid by the Maker when placing the order (i.e. paid ahead of execution) and are returned when the order is cancelled. If the fee was delayed until after the order is executed, it opens an opportunity to avoid paying the fee. For example, if the Maker waited until a Fill came through from a Taker and then reneged on the order, they would lose only the deposit on the order, but not the fee, reducing the economic consequences of the deposit itself.

Fees are paid by the Taker when filling the order (i.e. paid ahead of knowing whether you are the winning Taker) and are returned if another Taker fills the order before you. If the fee was delayed until after the order was taken off of the books it would present an opportunity to manipulate the orderbook and grief makers who would have to replace those orders unnecessarily.

Verifying reachability

The Relayer ensures that the Maker and Taker are reachable, i.e. that there is bandwidth sufficient on both chains of a transaction so that the Relayer could complete a transaction with the identified node as though the Relayer itself were the counterparty.

The Relayer verifies reachability of the Maker when the Maker places the order. If the Maker is not reachable, the Relayer will reject the order and refund the deposit and fee.

The Relayer verifies reachability of the Taker when the Taker attempts to fill an order. If the Taker is not reachable, the Relayer will reject the fill and refund the deposit and fee.

The Relayer verifies reachability of the Maker when the Taker attempts to fill the order since the channel bandwidth may have been exhausted or channels may have been closed after the the Maker placed the order. If the Maker is not reachable, the Relayer will reject the fill and cancel the order, but keep the deposit and fee.

The Relayer performs this function in order to ensure that trading runs as smoothly as possible. The Lightning Network is immature and not well-connected, particularly on some of the chains we plan to use (e.g. Litecoin), so many trades would fail due to unreachability, leading to lost deposits and bad experiences for traders.

Cancelling orders on disconnect

Makers open streaming channels to the Relayer while an order is open in order to receive notification of when to execute the swap. Due to the nature of the Sparkswap Network requiring nodes to stay online to participate, a Maker dropping the stream constitutes a disconnect, and the order in question is cancelled, with refunds of fees and deposits where appropriate.

This mirrors the common functionality of major traditional and cryptocurrency exchanges, and keeps the orderbook up to date with live orders only.

Opening channels

When a new participant wants to trade on Sparkswap, they need two channels open to their Lightning Node:

  • An outbound channel in their starting currency, with a balance on their side and a zero balance on the peer’s side to facilitate trading from their starting currency
  • An inbound channel in their desired currency, with a zero balance on their side, and a significant balance on the peer’s side to facilitate transfers from their desired currency

Creating the outbound channel is simple enough, but getting in inbound channel opened to you on a chain that you do not hold currency on is not all that easy, for two reasons:

  • You may not have currency on the desired chain at all, so would be unable to create the open channel transaction on the blockchain
  • You are not well connected to the Lightning Network for that chain, providing little value for anyone to open a channel to you

In order to bridge this gap, the Relayer provides functionality to open channels in particular currencies to nodes that request it.

← Swaps on SparkswapTrade Lifecycle →
  • Responsibilities of the Relayer
    • Order Deposits
    • Order Fees
    • Verifying reachability
    • Cancelling orders on disconnect
    • Opening channels
Sparkswap
Docs
Sparkswap OverviewBroker OverviewBroker RPC API Reference
Community
GitHubDiscordTwitter
Copyright © 2019 Sparkswap