Parties and Legs

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:

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

{
  "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 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 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:

{
  "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

Getting Started

Core Concepts

Guides

Smart Contracts

Parties

Party fields

Roles

Wallet addresses and escrow

Example: providing party details in an instruction

Cross-platform parties

Legs

Leg fields

Instrument ID formats

Who deposits to escrow?

How legs relate to parties

How legs map to escrow deposits

Multiple legs

​Parties

​Party fields

​Roles

​Wallet addresses and escrow

​Example: providing party details in an instruction

​Cross-platform parties

​Legs

​Leg fields

​Instrument ID formats

​Who deposits to escrow?

​How legs relate to parties

​How legs map to escrow deposits

​Multiple legs

Parties

Party fields

Roles

Wallet addresses and escrow

Example: providing party details in an instruction

Cross-platform parties

Legs

Leg fields

Instrument ID formats

Who deposits to escrow?

How legs relate to parties

How legs map to escrow deposits

Multiple legs