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

# Parties and Legs

> Who participates in a settlement and what obligations they have.

## Parties

A party represents an entity in a settlement with a specific role. Party details are provided inline when submitting instructions - there is no separate registration step.

### Party fields

| Field                | Description                                                                       |
| -------------------- | --------------------------------------------------------------------------------- |
| `role`               | The party's role in the settlement (e.g. `buyer`, `seller`, `lender`, `borrower`) |
| `external_reference` | Your platform's identifier for this entity (e.g. user ID, account number)         |
| `name`               | Optional display name for the entity                                              |
| `wallet_address`     | The blockchain wallet used for escrow deposits and receiving assets               |
| `status`             | `confirmed` (both parties confirmed from creation via bilateral instructions)     |

### Roles

Roles are defined by the template's `required_roles` field. Every settlement must include parties covering all required roles. Role names are flexible - the template defines what roles are needed.

Common role patterns:

* **DvP**: `buyer`, `seller`
* **Repo**: `cash_provider`, `securities_provider`
* **Lending**: `lender`, `borrower`

### Wallet addresses and escrow

The `wallet_address` field is used for off-chain identification and for recipient reveal at settlement execution time. With the commitment-based deposit scheme:

1. **Deposit authorization** - Each leg has a `deposit_secret` (random 32 bytes) and a `deposit_key` (keccak256 hash). The party deposits by providing the secret - no address-based validation. This preserves pre-execution privacy on public chains.
2. **Recipients bound at registration** - Each leg's recipient wallet is fixed permanently in `registerSettlement`. No later call can change where funds go, which is what makes execution autonomous and safe for any depositor to trigger.
3. **Pre-built calldata** - The API returns pre-built calldata for each leg so platforms can submit deposit transactions directly via their custody provider or any signing infrastructure.

Parties interact with escrow contracts directly using their own custody solution (MPC wallets, institutional signing infrastructure, etc.). KeyStone does not handle deposits or custody.

### Example: providing party details in an instruction

```json theme={null}
{
  "role": "seller",
  "party": {
    "external_reference": "seller-acct-001",
    "name": "Acme Securities",
    "wallet_address": "0xSellerWallet..."
  }
}
```

### Cross-platform parties

In cross-platform settlements using bilateral instructions, both platforms provide their own party details independently. Each platform submits their party's information in their instruction. When both instructions match, the settlement is created with both parties confirmed from the start.

See [Cross-Platform Settlements](/concepts/cross-platform) for the full flow.

## Legs

A leg represents a single obligation within a settlement - something that needs to move from one party to another.

### Leg fields

| Field                | Description                                                                           |
| -------------------- | ------------------------------------------------------------------------------------- |
| `leg_type`           | Type of obligation: `asset`, `payment`, `collateral`, `fee`                           |
| `instrument_id`      | What is being transferred (see [Instrument ID formats](#instrument-id-formats) below) |
| `quantity`           | How much                                                                              |
| `direction`          | `deliver` or `receive` from the party's perspective                                   |
| `party_role`         | Which party owns this obligation                                                      |
| `chain_id`           | Blockchain network (optional)                                                         |
| `token_standard`     | Token standard like ERC-20 (optional)                                                 |
| `status`             | Current status: `pending`, `locked`, `released`, `rolled_back`                        |
| `deposit_secret`     | Random 32-byte hex string for commitment-based deposits                               |
| `deposit_key`        | keccak256 hash of the deposit secret, registered on-chain                             |
| `external_reference` | Optional reference for this leg (e.g. trade ID)                                       |

### Instrument ID formats

The `instrument_id` identifies what is being transferred. The format depends on the asset type:

| Asset type              | Format           | Example                                           |
| ----------------------- | ---------------- | ------------------------------------------------- |
| On-chain token (ERC-20) | Contract address | `0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48`      |
| Stablecoin              | Contract address | `0x...` (the USDC contract on the relevant chain) |
| Tokenized security      | Contract address | `0x...` (the security token contract)             |

In production, always use the deployed contract address. In documentation examples, we sometimes use human-readable shorthand like `USDC` or ISINs like `US09311A1007` for clarity.

### Who deposits to escrow?

Only legs with `direction: "deliver"` require an escrow deposit. The party assigned to a deliver-direction leg is the one who must deposit the corresponding tokens to the escrow contract. Legs with `direction: "receive"` are fulfilled automatically when the escrow executes the atomic swap.

### How legs relate to parties

Legs reference parties by role, not by ID:

```json theme={null}
{
  "leg_type": "asset",
  "instrument_id": "0xTokenAddress",
  "quantity": "100",
  "direction": "deliver",
  "party_role": "seller"
}
```

This reads as: "The party with role `seller` delivers 100 units of token `0xTokenAddress`."

### How legs map to escrow deposits

Each leg with `direction: "deliver"` creates a deposit obligation on the escrow contract. The escrow uses a commitment scheme: each leg has a `deposit_key` (hash) registered on-chain, and the party deposits by providing the `deposit_secret` (preimage). The contract verifies `keccak256(secret) == depositKey`. When all deliver-direction legs have confirmed deposits, the atomicity gate passes.

The API automatically generates deposit secrets and returns them (along with pre-built calldata) in the settlement response so platforms can submit deposit transactions directly.

### Multiple legs

A settlement can have any number of legs. The template's `required_leg_types` ensures the minimum set is present:

| Settlement Type | Typical Legs                   |
| --------------- | ------------------------------ |
| DvP             | 1 asset leg + 1 payment leg    |
| Repo            | Securities + cash + return leg |
| Lending         | Securities + collateral + fee  |
| Netting         | N legs across multiple parties |