Full Pledge Mirroring and Settlement

In this implementation, parties agree on the duration of the trading period and all funds in the collateral account are pledged to only one secured party. You will need one account per EXCHANGE and the CUSTODIAN can provide several collateral accounts, one per asset.

Prerequisites

  1. Register your EXCHANGE API Operator on the CUSTODIAN's Ledger Enterprise workspace, find more in register a new API User .
  2. This API Operator need to be part of the collateral account rules, this step is done in advance on the custodian side.
  3. Subscribe to notifications, click here to read more about this.

Mirroring Pledges

pledge

In the full pledge setup, the whole balance is by design pledged to one exchange, this exchange being part of the transaction rules.

In this integration it's not yet possible for the exchange to acknowledge and reject pledges, this will be available with the multipledge model in Q2.

As an exchange you have 2 ways of mirroring the pledge, the active and the passive setup:

Active mirroring (recommended)

In this setup the exchange will pull information about the account using ledger enterprise API.

  1. Authenticate your API User, please find how to perform this operation here

  2. Get Account using the /accounts endpoint, you can find an example here

    As an exchange you will only be able to see collateral accounts shared by the end customers for each currency. It's name should look something like : ClientA COL tBTC or TL-0001-{code_asset}-{code_asset_manager}_{code_custodian}.

    Doing so you will also get the balance and the currency of the collateral reserved for you, this collateral was pledge by an inbound transaction from another account to this collateral account.

    ✅ Funds can't be withdrawn without the EXCHANGE and the CUSTODIAN approval, making it fully delegated to your exchange.

    You are able to check the account address on chain, and use any other source of truth to validate that the collateral is locked on this address directly on chain.

  3. Mirror the pledged balance on your system

    To mirror the pledge exchange need to have a system similar to a credit system, where the source are all of the collateral accounts from the asset manager held and secured by a custodian. Based on your the agreed credit limit you can enable a customer balance on your exchange. Please reach out to our technical account manager if you have any questions.

Passive mirroring

In this setup the exchange will pull information about the account using ledger enterprise API.

  1. Make sure you subscribe to ledger enterprise notifications, as described in the prerequisite section

  2. Watch for NEW_TRANSACTION_HAS_BEEN_RECEIVED when the collateral account receives a new transaction

    Inbound transaction from another account to this collateral account represent a pledge, this is fully recorded on chain. You can use the target id of the notification to get the transaction amount to see how much was pledged and find the account id to see the total balance pledged on this collateral account.

    ✅ Funds can't be withdrawn without the EXCHANGE and the CUSTODIAN approval, making it fully delegated to your exchange.

  3. Mirror the pledged balance on your system

    To mirror the pledge exchange need to have a system similar to a credit system, where the source are all of the collateral accounts from the asset manager held and secured by a custodian. Based on your the agreed credit limit you can enable a customer balance on your exchange. Please reach out to our technical account manager if you have any questions.

Trading - Out of scope

Ledger Enterprise don't cover the trading execution, as an OES (Off Exchange Settlement) technical provider we don't have visibility over the customer PNL. The EXCHANGE is responsible for maintaining the FUND PNL and initiating the settlement requests.

Initiating Settlement

The exchange need initiate the settlement using the amount consumed by the asset manager, this should be trivial knowing that the exchange is maintaining the PNL.

The settlement request takes the form a transaction creation request initiated by the Exchange which should be approved via Vault API or GUI. Considering the proposed workspace setup and the collateral account rules. The asset manager can be part of the approval flow, in this case he will need to approve first, we refer to this as a pre-approval. Only then the CUSTODIAN must provide the final approval.

settlement

Settlement flow Overview:

  1. Exchange creates the transaction COL -> Exchange.
  2. Exchange receives a notification for a new transaction creation request.
  3. Client approves OR rejects the transaction creation request.
  4. Exchange receives a notification for a new approval OR a rejection for the transaction creation request.
  5. Exchange processes the settlement which results in submitting the N transactions Exchange -> RES/COL.
  6. Vault sync RES/COL accounts.
  7. Custodian waits for all Exchange → RES/COL transactions to be synced by the RES/COL accounts.
  8. Custodian approves OR rejects the transaction creation request.
  9. If fully approved, the transaction is submitted and, once synced, the COL account balance is updated.
  10. Pledge is updated.

Implementation:

Exchange can create the settlement transaction (COL -> Exchange) via API.

Then the exchange is able to track the status on the approval of the settlement.

  • Active Approach: Exchange can check the pending requests of the COL accounts by searching for requests of type CREATE_TRANSACTION and which target_id relates to a transaction that is created by Exchange's api user. The current number of approvals for the request can be checked to confirm that the request has been pre-approved by Client.
  • Passive Approach: Exchange receives the event REQUEST_HAS_RECEIVED_AN_APPROVAL with the request_id once the request was approved by Client. The request info can then be fetched to double check that the type is CREATE_TRANSACTION and to extract the transaction_id . From the transaction id, one can fetch the full transaction info.

Additional checks can be performed to make sure the transaction is a settlement request:

  • Status should be PENDING_APPROVAL .
  • account_id must be a valid COL account id.
  • Recipient must be one of Exchange account addresses.

Then the transaction can be considered as of a settlement request and the settlement can be processed.

Exchange submits on chain his side of the trade (Exchange -> RES/COL) transactions. The rest of the workflow depends on Custodian final approval.

Once Custodian has approved the transaction creation request, Exchange receives the event REQUEST_HAS_REACHED_QUORUM for the same request_id.

Optional - Processing withdrawal request

unpledge

Unpledge Workflow Overview:

  1. Client creates the transaction to withdraw the funds from collateral COL -> RES.
  2. Exchange receives a notification when it’s time to approve the request.
  3. Exchange approves OR rejects the transaction creation request.
  4. Custodian receives a notification when it’s time to approve the request.
  5. Custodian approves OR rejects the transaction creation request.
  6. Exchange receives a notification for a fully approved OR a rejected transaction creation request.
  7. If fully approved, the transaction is submitted and, once synced, the COL account balance is updated.
  8. Pledge is updated, and exchange need to update the amount available on the exchange.

Implementation:

  • Active Approach: Exchange can check the pending requests of the COL accounts by searching for requests of type CREATE_TRANSACTION and status PENDING_APPROVAL relates to a transaction that is created by the asset manager you can match it to the source collateral account used and source currency.
  • Passive Approach: When Client creates the unpledge transaction request, Exchange receives the event REQUEST_HAS_REACHED_STEP with the request_id . The request info can then be fetched to double check that the type is CREATE_TRANSACTION and to extract the transaction_id . From the transaction id, one can fetch the full transaction info.

Additional checks can be performed to make sure the transaction is an unpledge:

  • Status should be PENDING_APPROVAL .
  • account_id must be a valid COL account id.
  • Recipient must be one of asset manager reserve account addresses.

As an exchange you also need to make sure theses funds are not in use on the exchange, it this balance is free you can approve the withdraw.

Then the CUSTODIAN also need to give his final approval for this transaction creation request. Once final, the exchange receives the event REQUEST_HAS_REACHED_QUORUM meaning that all of the approvals where received and that the transaction will be signed and broadcasted. You can also keep track of this request after the full approval.

Please don't hesitate to reach out for integration workshops from our technical account manager team for any questions.

Copyright © Ledger Enterprise Platform 2023. All right reserved.