> ## Documentation Index
> Fetch the complete documentation index at: https://docs.keystoneos.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Tokenised Repo

> How KeyStone handles tokenised repurchase agreement settlements.

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.

KeyStone handles repo as **two linked DvP settlements** - an opening leg and a closing leg. What happens between legs is not KeyStone's concern.

## KeyStone's role in repo

KeyStone settles both legs of a repo. The period between legs - collateral management, yield strategies, rehypothecation - is the counterparties' business.

| Concern                                | Who handles it                                        |
| -------------------------------------- | ----------------------------------------------------- |
| Settlement of opening leg              | KeyStone (atomic DvP)                                 |
| Settlement of closing leg              | KeyStone (atomic DvP)                                 |
| What lender does with bond during repo | Lender's choice (Aave Horizon, hold in custody, etc.) |
| Collateral management                  | Bilateral agreement between counterparties            |
| Maturity trigger                       | KeyStone (scheduling)                                 |
| Default enforcement                    | Legal agreement between counterparties                |

## What KeyStone does NOT do for repo

* Lock collateral for the repo duration (that is lending - Aave Horizon does this)
* Monitor collateral ratios (that is lending)
* Handle margin calls (that is lending)
* Enforce repayment (that is between the counterparties)
* Liquidate on default (that is between the counterparties)

## Lifecycle

```mermaid theme={null}
%%{init: {'theme': 'base', 'themeVariables': {'actorBkg': '#1a3a35', 'actorBorder': '#2DD4A8', 'actorTextColor': '#e0f2ef', 'actorLineColor': '#2DD4A8', 'signalColor': '#2DD4A8', 'signalTextColor': '#e0f2ef', 'noteBkgColor': '#162e2a', 'noteTextColor': '#e0f2ef', 'noteBorderColor': '#1AAF8B', 'activationBkgColor': '#1a3a35', 'activationBorderColor': '#2DD4A8', 'labelBoxBkgColor': '#1a3a35', 'labelBoxBorderColor': '#2DD4A8', 'labelTextColor': '#e0f2ef', 'loopTextColor': '#2DD4A8'}}}%%
sequenceDiagram
    participant BNY as Borrower
    participant KS as KeyStone
    participant HSBC as Lender
    participant Aave as Aave Horizon (optional)

    rect rgb(230, 245, 230)
        Note over KS: Opening leg settlement (KeyStone)
        BNY->>KS: Submit instruction (deliver bond, receive USDC)
        HSBC->>KS: Submit instruction (deliver USDC, receive bond)
        KS->>KS: Match, compliance, create on-chain
        Note over KS: Both parties deposit to escrow
        Note over KS: Contracts auto-execute and finalize
        KS->>HSBC: Bond delivered
        KS->>BNY: USDC delivered
    end

    rect rgb(245, 240, 230)
        Note over BNY,HSBC: Repo period (NOT KeyStone)
        Note over BNY: Uses cash for operations
        Note over HSBC: Holds bond. Options:
        HSBC-->>Aave: Deposit bond into Aave Horizon for yield
        Note over HSBC: Or: hold in custody
    end

    rect rgb(230, 245, 230)
        Note over KS: Closing leg settlement (KeyStone)
        Note over KS: Maturity trigger (automatic or manual)
        HSBC-->>Aave: Withdraw bond from Aave (if deposited)
        BNY->>KS: Submit instruction (deliver USDC+interest, receive bond)
        HSBC->>KS: Submit instruction (deliver bond, receive USDC+interest)
        KS->>KS: Match, compliance re-screen, create on-chain
        Note over KS: Both parties deposit to escrow
        Note over KS: Contracts auto-execute and finalize
        KS->>BNY: Bond returned
        KS->>HSBC: USDC + interest delivered
    end
```

## How Aave Horizon composes

Aave Horizon is a pooled lending protocol for institutional RWA collateral. KeyStone is bilateral atomic settlement infrastructure. They are fundamentally different products that compose naturally:

* **KeyStone** settles both legs of the repo (opening DvP and closing DvP)
* **Between legs**, the lender optionally deposits the received bond into Aave Horizon to earn yield during the holding period
* **Collateral management** (margin monitoring, haircuts, liquidation) is NOT KeyStone's concern
* **Default enforcement** follows the same model as TradFi repo: bilateral legal agreements govern

## Trade types

Settlements carry an optional `trade_type` field:

| Trade type          | Description                                                                                     |
| ------------------- | ----------------------------------------------------------------------------------------------- |
| `repo_open`         | The opening leg. Created by the platform with `repo_terms` (tenor, rate, haircut, margin band). |
| `repo_close`        | The closing leg. Auto-created by KeyStone at maturity with reversed legs.                       |
| `spot_dvp` / `null` | A standard DvP settlement (default).                                                            |

## Maturity handling

Maturity is derived from the opening settlement's `repo_terms`: it falls `tenor_days` after the opening settlement is created. When the opening settlement finalizes and maturity arrives, KeyStone automatically creates the closing settlement; the closing payment amount is derived from `tenor_days`, `rate_bps`, and the opening payment quantity.

**Manual trigger**: Administrators can trigger maturity early via the admin API:

```bash theme={null}
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) |

The closing settlement goes through the full compliance and escrow flow independently. Compliance is re-screened because parties may have been sanctioned between opening and closing.

## Default scenario

If the borrower does not show up for the closing leg:

* KeyStone records the failed settlement
* The lender already has the bond (from the opening DvP)
* Legal recourse governs (bilateral agreement between institutions)
* Legal agreements between the counterparties handle defaults

<Note>
  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, and its own compliance checks.
</Note>