This SIP adds limit order functionality to the Synthetix exchange, without modifying the core exchange contracts.
\nTo keep the integrity of the core Synthetix contracts in place, we propose the creation of a separate layer of “advanced mode” trading contracts to enable additional functionality. The primary contract is a limit order contract. The exchange users can place limit orders on it and send the order source amount to it. Additionally, they specify the parameters of limit orders, including destination asset price and execution fees. Limit orders set by the user are executed at the right time by \"execution nodes\" that recieve the execution fee in exchange.
\nTo increase the flexibility of the Synthetix exchange, limit order functionality is needed so users can effectively trade synthetic assets. While limit orders can be trivial to implement in the case of centralized exchanges, in the case of a DEX such as Synthetix, limit orders can be challenging in terms of security guarantees and trustlessness due to client unavailability.
\nNOTES:
\n^0.5.16.Order of deployment:
\nImplementation contract is deployedImplementationResolver contract is deployed where the address of the Implementation contract is provided to the constructor as an initialImplementationProxy contract is deployed with the address of the ImplementationResolver provided to the constructor.Implementation.initialize() is called on the Proxy address.The Implementation contract stores no state and no funds and is never called directly by users. It is meant to only receive forwarded contract calls from the Proxy contract.
\nAll state read and write operations on this contract are stored in the Proxy contract state. In the event of an implementation upgrade, the Proxy state would become automatically accessible to the new Implementation.
A uin256 variable that tracks the highest orderID stored.
\nAn address variable that contains the address of the Synthetix exchange contract
\nA mapping between uint256 orderIDs and LimitOrder structs
struct LimitOrder {\n address payable submitter;\n bytes32 sourceCurrencyKey;\n uint256 sourceAmount;\n bytes32 destinationCurrencyKey;\n uint256 minDestinationAmount;\n uint256 weiDeposit;\n uint256 executionFee;\n uint256 executionTimestamp;\n uint256 destinationAmount;\n bool executed;\n}\nfunction initialize(address synthetixAddress, address _addressResolver) public;\nThis method can only be called once to initialize the proxy instance.
\nfunction newOrder(bytes32 sourceCurrencyKey, uint sourceAmount, bytes32 destinationCurrencyKey, uint minDestinationAmount, uint executionFee) payable public returns (uint orderID);\nThis function allows a msg.sender who has already given the Proxy contract an allowance of sourceCurrencyKey to submit a new limit order.
sourceAmount of the sourceCurrencyKey Synth from the msg.sender to this contract via transferFrom.orders mapping where the key is latestID + 1. The order's executed property is set to false.latestID variable.msg.value to be more than the executionFee in order to refund node operators for their exact gas wei cost in addition to the executionFee amount. The remainder will be transferred back to the user at the end of the trade.Order event for node operators including order data and orderID.orderID.function cancelOrder(uint orderID) public;\nThis function cancels a previously submitted and unexecuted order by the same msg.sender of the input orderID.
submitter property to be equal to msg.sender.executed property to be equal to be false.sourceAmount and deposited msg.valueorders mapping.Cancel event for node operators including the orderIDfunction executeOrder(uint orderID) public;\nThis function allows anyone to execute a limit order.
\nIt fetches the order data from the orders mapping and attempts to execute it using Synthetix.exchange(), if the amount received is larger than or equal to the order's minDestinationAmount:
executionFee amount from the user's wei deposit.executed property is changed to true, the executionTimestamp property set to block.timestamp and destinationAmount set to the received amount.Execute event is emitted with the orderID for node operatorsIf the amount received is smaller than the order's minDestinationAmount, the transaction reverts.
function withdrawOrders(uint[] orderID) public;\nThis function allows the sender to withdraw funds associated with an array of executed orders as soon as the Synthetix fee reclamation window for each of the order has elapsed.
\nIt iterates over each order's data from the orders mapping, if each order's submitter is equal to msg.sender, has the executed property equal to true and executionTimestamp + Exchanger.waitingPeriodSecs() < block.timestamp:
destinationAmount of the destinationCurrencyKey is transferred to msg.sender using Synth.transferAndSettle()orders mapping.Withdraw event is emitted with the orderID.event Order(uint indexed orderID, address indexed submitter, bytes32 sourceCurrencyKey, uint sourceAmount, bytes32 destinationCurrencyKey, uint minDestinationAmount uint executionFee, uint weiDeposit)\nThis event is emitted on each new submitted order. Its primary purpose is to alert node operators of newly submitted orders in realtime.
\nevent Cancel(uint indexed orderID);\nThis event is emitted on each cancelled order. Its primary purpose is to alert node operators that a previously submitted order should no longer be watched.
\nevent Execute(uint indexed orderID, address executor);\nThis event is emitted on each successfully executed order. Its primary purpose is to alert node operators that a previously submitted order should no longer be watched.
\nevent Withdraw(uint indexed orderID, address indexed submitter);\nThis event is emitted on each successfully withdrawn order.
\nThe proxy contract receives all incoming user transactions to its address and forwards them to the current implementation contract. It also holds all deposited token funds at all times including future upgrades.
\nAll calls to this contract address must follow the ABI of the current Implementation contract.
constructor(address ImplementationResolver) public;\nThe constructor sets the ImplementationResolver to an internal global variable to be accessed by the fallback function on each future contract call.
function() public;\nFollowing any incoming contract call, the fallback function calls the ImplementationResolver's getImplementation() function in order to query the address of the current Implementation contract and then uses DELEGATECALL opcode to forward the incoming contract call to the queried contract address.
This contract provides the current Implementation contract address to the Proxy contract.\nIt is the only contract that is controlled by an owner address. It is also responsible for upgrading the current implementation address in case new features are to be added in the future.
constructor(address initialImplementation, address initialOwner) public;\nThe constructor sets the initialImplementation address to an internal global variable to be access later by the getImplementation() method. It also sets the initialOwner address to the owner public global variable.
An address variable that stores the contract owner address responsible for upgrading the implementation contract address.
\nfunction changeOwnership(address newOwner) public;\nThis function allows only the current owner address to change the contract owner to a new address. It sets the owner global variable to the newOwner argument value and emits a NewOwner event.
function upgrade(address newImplementation) public;\nThis function allows only the current owner address to upgrade the contract implementation address.
It sets the internal implementation global variable to the newImplementation global variable.
Following the upgrade, the Upgraded event is emitted.
event NewOwner(address newOwner);\nThis event is emitted when the contract owner address is changed.
event Upgraded(address newImplementation);\nThis event is emitted when finalizeUpgrade() is called.
The Limit Order Execution Node is an always-running node that collects NewOrder events from the proxy contract and executes each order when its minDestinationAmount condition is met by the Synthetix oracle (Synthetix ExchangeRates.sol contract).
executionFee equal to or larger than a pre-configured minimum.This service listens for new Ethereum blocks in realtime. On each new block, the service queries the contract for currently executable orders.
\nIf any executable limit orders are found, they are passed to the Execution Service
\nIn order to determine whether an orderID should be immediately executed, the service follows the following steps:
orderID. If a record is found, this order will not be submitted.executeOrder contract function while passing the orderID. If the attempt fails, this is likely because the order's deposited wei funds are insufficient to fully recover the gas cost of this transaction + the executionFee.wei to cover this transaction cost. If the balance is insufficient, an email notification must be sent to the node operator.After the checks have passed, the order is executed:
\norderID is submitted to the executeOrder function in a new transactionorderID is temporarily stored in the local database to prevent future duplicate transactions until the transaction is included in a block.The execution service then listens for the transaction status.\nIf the transaction is successfully mined and but the EVM execution has failed:
\norderID from the local databaseorderID will then be collected again by the Watcher Service as soon as its conditions are met, starting from the next block.This library is proposed in order to provide a simple Javascript interface to the limit order functionality of the Synthetix limit order contract.
\nThe library must allow a simple interface to the following operations:
\nconst instance = new SynthLimitOrder(ethereumProvider)\nThe library must expose a SynthLimitOrder class. The user instantiates a class instance by passing a valid ethereum provider with signing capabilities (e.g. Metamask) to the constructor.
const orderID = await instance.submitOrder({\n sourceCurrencyKey, // bytes32 string\n sourceAmount, // base unit string amount\n destinationCurrencyKey, // bytes32 string\n minDestinationAmount, // base unit string amount\n weiDeposit, // wei string amount\n executionFee // wei string amount\n})\nThis method allows the user to submit a new limit order on the contract by calling the newOrder contract function.
This method also automatically attempts to sign an ERC20 approve transaction for the sourceCurrencyKey token if a sufficient allowance is not already present for the contract.
It returns a Promise<string> as soon as the transaction is confirmed where the string contains the new order ID.
await instance.withdraw()\nThis method allows the user to withdraw funds from all executed orders on the contract that have passed the fee reclamantion duration.
\nThe method fetches all historical Executed events from the contract filtered by the user's address as the submitter and queries each order's current state using StateStorage.getOrder. If the order's executed property is true and executedTimestamp + 3 minutes is larger than the current timestamp, the order is is added to the array of order IDs sent to the Proxy contract's withdrawOrders function.
It returns a Promise<void> as soon as the transaction is confirmed.
await instance.cancelOrder(orderID)\nThis method cancels an active order by calling the cancelOrder contract function.
It returns a Promise<void> as soon as the transaction is confirmed.
const order = await instance.getOrder(orderID)\nThis method allows the user to query the contract for a specific order number by querying the StateStorage contract getOrder function.
It returns a promise that resolves with an Order object:
interface Order {\n submitter: string;\n sourceCurrencyKey: string;\n sourceAmount: string;\n destinationCurrencyKey: string;\n minDestinationAmount: string;\n weiDeposit:string;\n executionFee:string;\n executionTimestamp:string;\n destinationAmount:string;\n executed:boolean;\n}\nconst order = await instance.getAllActiveOrders()\nThis method allows the user to query the contract for an array all active orders submitted by the user's address. This array is constructed by querying a list of all past Order contract events filtered by the user's wallet address as the submitter. Each orderID is passed to the getOrder javascript method before being included in the returned array in order to ensure that the order is still active.
It returns a Promise<Order[]> where an Order follows the interface above.
By allowing anyone to run “limit order execution nodes” and compete for limit order execution fees, we achieve order execution reliability and censorship-resistance through permissionless-ness. These are especially important in the context of limit orders, where censorship or execution delays might cause trading losses.
\nWe use an upgradable proxy pattern in order to allow a present owner address to upgrade the core implementation contract at any time.
\nTest cases to be provided with implemented code.
\nNot started. Spec complete and ready for community review.
\nCopyright and related rights waived via CC0.
"}},"pageContext":{"id":"016ee562-3a18-5bf7-a6a1-3c9735a11017","frontmatter__sip":54,"__params":{"frontmatter__sip":"54"}}},"staticQueryHashes":[]}