Ledger Engine

UTXO Ledger Engine Specification

The UTXO Ledger Engine defines the logic for maintaining an immutable history of all deposits, trades, and settlements occurring on a Participating Interface. The latest state of the engine can be used to derive the balances of all traders with assets deposited on the PI.

Both PIs and SDPs must run an instance of the engine. SDPs must validate that UTXOs included as inputs and generated as outputs in all trades emitted by the PI are the result of correctly running the UTXO engine. Thus, the core logic of the engine must be deterministic, so that given the same order of deposits and trades, the PI and all servicing SDPs reach the same ledger state.

Configuration

• MUST require user to specify whether the engine is being run by a PI or an SDP

SDP Operation

• MUST provide an endpoint for the SDP to send a Trade and call the validateTrade function, responding with the result

PI Operation

• MUST provide an endpoint for the PI to send a TradeParams and call the prepareTrade function, responding with the result

• MUST provide an endpoint for the PI to send a Deposit and call the prepareDeposit function, responding with the result

• MUST provide and endpoint for the PI to send a SettlementRequest and call prepareSettlement

• MUST strictly sequence and process each StateTransition provided by the PI

Ledger Database

• MUST store all UTXOs in a database, unhashed

• MUST support querying UTXOs by any of their attributes

Functions

Note that every function defined below MUST be atomic.

validateTrade

Given Trade:

• extract TradeParams and pass to determineTradeUTXOs

• using the result of determineTradeUTXOs:

  • hash each input UTXO for side A

  • hash each input UTXO for side B

  • hash each output UTXO for side A

  • hash each output UTXO for side B

• extract inputUTXOs and outputUTXOs from Trade

• if hashes of input and output UTXOs generated match UTXO hashes in Trade, return true to indicate a valid trade

• if UTXOs don't match, return false along with an UnsignedTrade with the correct input and output UTXOs

prepareTrade

Given TradeParams :

• call determineTradeUTXOs with TradeParams

• using the result of determineTradeUTXOs:

  • hash each input UTXO for side A

  • hash each input UTXO for side B

  • hash each output UTXO for side A

  • hash each output UTXO for side B

• using TradeParams and the input and output UTXO hashes create an UnsignedTrade

• append output UTXOs to the ledger

• return the UnsignedTrade

prepareSettlement

Given SettlementRequest:

• query for all unspent UTXOs with the same asset and trader to use as inputs

• for all UTXOs above, generate a SettledUTXO to use as output

• hash all input and output UTXOs

• use SettlementRequest and UTXO hashes to create SettlementParams

• return the SettlementParams

prepareDeposit

Given Deposit:

• call hashDeposit

• using Deposit and the result of hashDeposit, create a DepositUTXO

• append the DepositUTXO to the ledger

• return the hash of the deposit

determineTradeUTXOs

Given TradeParams:

• determine TradeSide for trader that submitted Order a and call determineInputUTXOs

• determine TradeSide for trader that submitted Order b and call determineInputUTXOs

• use TradeSide and input UTXOs determined from Order a , and trader of Order b to call generateOutputUTXOs

• use TradeSide and input UTXOs determined from Order b , and trader of Order a to call determineOutputUTXOs

• return all input and output UTXOs

determineInputUTXOs

Given TradeSide:

• query for all unspent UTXOs with same asset and trader as specified in the TradeSide, sorted descending by UTXO hash

• iterate through UTXOs from the query result and add to a list until the sum of the amounts of the selected UTXOs is greater than or equal to the amount in the TradeSide

• return the list of selected UTXOs

generateOutputUTXOs

Given TradeSide , list of input UTXOs, and address counterParty:

• iterate through input UTXOs and generate symmetric output UTXOs

  • if the sum of the amounts in input UTXOs is greater than the amount in the TradeSide, then the final input UTXO will generate a second output UTXO granting the remainder to the counterParty