Settlement 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.

Pre Polymesh

Let's describe the simple exchange system before we integrate it with Polymesh.

The setup

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.tsx page 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 id serves as the identifier of the order. At the same time, because we do not have identifiers for traders, this id serves as an identifier for traders too, as can be seen in SettlementParty below. Of course, an entity can create multiple orders, just by picking an available id.
• SettlementParty, an object to describe a party involved in a trade. In effect, the id of the order / trader.
• SettlementInfo, an object to describe the result of matched orders.
• FullSettlementInfo, the same but with an id.

There are a couple of extra functions to note:

• a createByMatchingOrders function to assist in creating a SettlementInfo out of 2 matching OrderInfo.
• a more complex matchOrders function 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.

Post Polymesh

Time to integrate with Polymesh. What needs to be done?

The setup

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.

On objects:

• in OrderInfo, we add information about the trader's trading portfolio.
• in SettlementParty, we add the same information about the trader.
• In SettlementInfo, we add a way to reference a settlement instruction.

On services:

• in exchangeDbFs, we add a way to check that the Polymesh information is valid.
• which means the exchangeDbFactory needs 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.

On pages:

• 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:

Conclusion

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.