Skip to main content

Broker to Broker state channels

Smart Contracts Architecture

We still need to define the approach for custody smart contract architecture

Single smart contract- Simplify the deployment of a broker (no SM to deploy)
- No external transfer for brokers settlement (save gas?)
- Big TVL for XLN network
- User doesn't need to allow spending on every broker
- Broker doesn't need to deposit collateral, they can use user funds directly
- Might be a SPOF
- Complex smart contract
One smart contract per broker, one for XLN collateral- Simple smart contract
- Easy to inspect broker funds
- Broker can govern his smart contract
- Broker can exit scam
- Broker is responsible of securing the governance
One smart contract per broker, none for XLN collateral- Broker doesn't need to deposit collateral- XLN has access to brokers funds

Single smart contract

Only one smart contract would be used for the whole network. For deploying a new broker Openware will just have to register to the start contract this new broker (public key, public url).

In this case the collateral need is a lot less necessary, since all funds are already sitting on the smart contract, we just need to evaluate the risk of dispute. The broker would need to cover the cost of lost dispute (penalty).

One smart contract per broker, one for XLN collateral

Each broker would have his own smart contract.

One smart contract per broker, none for XLN collateral

General overview

B2B state channels are specific, each broker smart contract is involved in a transaction, also XLN is used to lock the value of the trade from brokers collaterals and manage disputes.


State channel initialization sequence

Broker A-->>XLN: Request a collateral lock
XLN-->>Broker A: Provide a signed lock
Broker A->>Broker B: Initiate the state channel with lock A
Broker B-->>XLN: Request a collateral lock
XLN-->>Broker B: Provide a signed lock
Broker B->>Broker A: Add lock B

Trading sequence

Broker A->Broker B: Create matching order
Broker B->Broker A: Match order (update balance)

Happy ending sequence

Broker A->Broker B: Request final state signature
Broker B->Broker A: Sign final state
  • Broker A use the final signed state to withdraw funds from Broker B smart contract
  • Broker B use the final signed state to withdraw funds from Broker A smart contract

Dispute sequence

  • If one of the broker doesn't accept to sign the final state, a dispute is open
  • Logs of the state channel must be provided by brokers to XLN
  • XLN must be able to close the dispute with automatic processing of those logs

TBD: dispute resolution process

State format

struct FixedPart {
uint256 chainId;
address[] participants;
uint48 channelNonce;
address appDefinition;
uint48 challengeDuration;
struct VariablePart {
bytes outcome;
bytes appData;

State appData

buBalance updateCurrent state of the platforms balances respectively in each other platform.
oosOpen orders summaryThe sum of amounts in base and quote of all open open orders for both platforms, they can open orders in the other platform remote markets.
clCollateralCollaterals locked by XLN for the current trading session.

In the following example we use "0xa" as platform A address and "0xb" as platform B address, platform A will buy 0.1 ETH for 200 USDC on platform B, both platforms will use a collateral from XLN of 0.011 BTC worth of 220 USDC.

"cl": {
// Collateral of platform A
"0xa": [
// [ETH mainnet, WBTC address, 0 WBTC available, 0.11 WBTC locked]
["0x1", "0x2260fac5e5542a773aa44fbcfedf7c193bc2c599", "0", "0.011"]
// Collateral of platform B
"0xb": [
// [ETH mainnet, WBTC address, 0 WBTC available, 0.11 WBTC locked]
["0x1", "0x2260fac5e5542a773aa44fbcfedf7c193bc2c599", "0", "0.011"]
"bu": {
// Balance of platform A on platform B
"0xb": {
"0xa": [
// [ETH mainnet, ETH (native) token, 0 ETH available, 0.1 ETH locked]
["0x1", "0x0", "0", "0.1"],
// Balance of platform B on platform A
"0xa": {
"0xb": [
// [ETH mainnet, USDC address, 0 USDC available, 200 USDC locked]
["0x1", "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "0", "200"]
"oos": {
// Summary of open orders of platform A on platform B "eth/usdc" market
"0xb" : {
"0xa" : {
"eth/usdc": {"b": ["0.2", "100", "200", "150"]}
// {"buy": [Average amount in base, Min price of orders, Max price of orders, Average amount in quote]}

B2B RPC costs

Every call from one broker to another will be charged by the receiver broker, the cost depends on network and CPU usage.

RPC calls cost table

RPCWho is chargedDB r/wAverage message sizeDescription
Get orderbook snapshotrequestor0/010 kbRequest an orderbook snapshot and subscribe to update events
Push orderbook incrementinitiator0/1100 bytesPublish an orderbook change event
Push trade event??0/1100 bytesNotification about a trade appended remotely, not involving the receiving broker (public event).
Create remote orderinitiator0/1100 bytesCreate an order remotely, it's supposed to match an existing remote order
Update remote orderinitiator1/1100 bytesUpdate of cancel an existing order
Notify order updateinitiator0/1100 bytesNotification about an order match, update or cancel of the receiving broker (private event).


  • What currency can be used as collateral? XLN, USDC, WBTC, WETH, multi-currencies?
  • Should we initialize the state channel only once we have both locks?


  • What if the smart contract doesn't hold enough funds for the withdraw, should we lock the collateral until the withdraw is performed?
  • Collateral value might change over time, if the process is long we might need to liquidate the collateral.