Settlement Example App
A walk through the example app
After learning about the SDK elements that work for settlement and custodianship, let's have a look at a simplified example of what it would take to integrate an existing system with Polymesh. For this example, we will consider the case of a stock exchange onto which brokers place orders for their customers. To simplify, and not overburden the reader with elements not relevant to learning about Polymesh, we did not add any authentication nor authorisation mechanism. Nor did we implement any sophisticated order matching algorithm.
Let's describe the simple exchange system before we integrate it with Polymesh.
4 pages are served:
index.tsx, a page to link to the 3 others.
trader.tsx, a page for traders and custodians to see, put and delete orders.
exchange.tsx, a page for the exchange "manager" to see all orders in 2 columns, and match 1 sell order with 1 buy order and thereby create 1 trade.
custodian.tsx, a page for the traders and custodians to see their trades' pending settlements and indicate the actions they have taken.
There is a rudimentary server that exposes a simple API:
api/trader/[id].ts, an end point for traders and custodians to get, put and delete orders. Orders are identified by their
id, and no restriction is enforced here. Anyone can use any
id, including someone else's.
api/trades.ts, an end point for anyone to retrieve all trades. This is used by the
exchange.tsxpage to be able to present the buy and sell orders.
api/settlements.ts, an end point for:
- the exchange to post matching orders, thereby creating a pending settlement.
- the traders and custodians to get all relevant pending settlements.
api/settlement/[id].ts, an end point place for traders and custodians to get, patch and delete settlements. Settlements are identified by their
id, which is decided by the exchange server. When traders and custodians patch a settlement, that is to indicate whether they have paid / transferred their end of the bargain. Yes, there is no verification, it is based on trust...
On the server, basic services are running:
exchangeDbFs.ts, a service to store orders from traders and custodians on disk in a large JSON file, instead of a proper database, for simplicity's stake.
settlementDbFs.ts, a similar service, this time to store pending trade settlements, on disk in a large JSON file.
The system describes its information in terms of:
OrderInfo, an object to describe an order information.
AssignedOrderInfo, the same but with an
id. Note that this
idserves as the identifier of the order. At the same time, because we do not have identifiers for traders, this
idserves as an identifier for traders too, as can be seen in
SettlementPartybelow. Of course, an entity can create multiple orders, just by picking an available
SettlementParty, an object to describe a party involved in a trade. In effect, the
idof the order / trader.
SettlementInfo, an object to describe the result of matched orders.
FullSettlementInfo, the same but with an
There are a couple of extra functions to note:
createByMatchingOrdersfunction to assist in creating a
SettlementInfoout of 2 matching
- a more complex
matchOrdersfunction that assists in saving the created settlement into the server, and updating or deleting the orders.
How it looks
Let's say that trader 1 puts a buy order and trader 3 puts a sell order:
Then, when the exchange looks at the current orders:
Then after clicking Submit the match:
So 50 shares of ACME have been traded for 35 USD apiece. It is time to see this settlement from the point of view of the trader 1, or its custodian:
Trader 1 was the buyer, so it needs to click Mark as paid when it has been done. Since the trade is about 2 parties, the seller also needs to accept, so let's look at it from the seller's point of view:
After clicking Mark as transferred, the trade is considered complete. Of course it is possible for either party to reject it.
Time to integrate with Polymesh. What needs to be done?
Let's go from the bottom up.
On the configuration:
- Some basic information is added about the exchange server's Polymesh account mnemonic, and the default settlement venue of the exchange.
- A CLI tool is added to handle the setup in a more pleasant way.
OrderInfo, we add information about the trader's trading portfolio.
SettlementParty, we add the same information about the trader.
SettlementInfo, we add a way to reference a settlement instruction.
exchangeDbFs, we add a way to check that the Polymesh information is valid.
- which means the
exchangeDbFactoryneeds to be adjusted to prepare the Polymesh API.
- we also add a new service
SettlementEnginePoly, which handles the publication of the settlement instruction on Polymesh.
On API end points:
- No real changes other than using the right types and exceptions.
- We add a helper to get the Polywallet.
- On the trader page, we make it possible to also pick custodied portfolios, so that custodians can choose them.
- We also make it possible for the trader to set a custodian on a given portfolio.
- Because of that, we also add a way to show the incoming requests.
- The exchange page does not really change.
- The custodian settlement page adds a way to load instructions that are in the exchange venue but are not part of what the exchange knows about.
- Additionally, the custodian page affirms the relevant legs, before informing the exchange server that a trade side has been paid or transferred.
- Of course, the custodian page needs to check the identity found in the Polywallet and activate the buttons only when the affirmation is possible.
How it looks
There is more information to provide when submitting a buy order:
And a sell order:
The exchange page did not change. The custodian settlement page has more too:
That's what it takes.
- Make your server able to access Polymesh.
- Store a bit more information in your database.
- Make your Web pages a bit more decentralised by having them:
- trust the exchange server but verify.
- do some actions that do not involve the exchange server.