A tokenised repurchase agreement (repo) is a two-part transaction where one party sells a tokenised bond to another and agrees to repurchase it at a later date, typically at a slightly higher price. It is one of the most common instruments in fixed-income markets and is frequently used for short-term borrowing against collateral.
KeyStone models a repo as two linked DvP settlements: an opening leg and a closing leg.
How repos work in KeyStone
Instead of building a separate repo engine, KeyStone reuses the same settlement state machine and escrow infrastructure that powers standard DvP. A repo is simply two settlements linked by a parent-child relationship.
| Settlement | Category | What happens |
|---|
| Opening | repo_open | Seller delivers bond tokens, buyer delivers USDC. Atomic swap via escrow. |
| Closing | repo_close | Reverse swap at maturity. Buyer returns bonds, seller returns USDC (plus interest). |
FINALIZED. It inherits the same parties and template, but reverses the legs (buyer becomes deliverer of bonds, seller becomes deliverer of USDC).
Lifecycle
Settlement categories
Settlements now carry an optional settlement_category field:
| Category | Description |
|---|
repo_open | The opening leg of a repo. Created by the platform. |
repo_close | The closing leg of a repo. Auto-created by KeyStone at maturity. |
null | A standard DvP settlement (default). |
Maturity handling
The opening settlement includes a maturity_at timestamp that defines when the repo closes.
Automatic maturity: A background worker monitors repo_open settlements that have reached FINALIZED. When maturity_at passes, it automatically creates the corresponding repo_close settlement and enqueues it for processing.
Manual trigger: Administrators can trigger maturity early via the admin API:
POST /v1/admin/settlements/{id}/trigger-maturity
Leg reversal at closing
When the closing settlement is created, the legs from the opening settlement are reversed:
| Opening leg | Closing leg |
|---|
| Seller delivers bond | Buyer delivers bond (return) |
| Buyer delivers USDC | Seller delivers USDC + interest (return) |
direction and party_role fields are swapped. The closing settlement’s USDC quantity may differ from the opening (reflecting the repo rate/interest).
Parent-child linking
The closing settlement stores a parent_settlement_id pointing to the opening settlement. You can query all related settlements for a given repo:
GET /v1/settlements/{id}/related
State machine
Both opening and closing settlements use the same state machine. The closing settlement goes through the full compliance and escrow flow independently - there are no shortcuts. This ensures:
- Compliance is re-screened at closing (parties may have been sanctioned between opening and closing)
- Escrow protections apply to both legs
- Full audit trail for both legs
A repo is not a single settlement with two phases. It is two independent settlements linked by a parent-child relationship. Each settlement has its own events, its own escrow registration, and its own compliance checks.
