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
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.
- Recipient reveal - Wallet addresses are revealed only at execution time when the coordinator calls
executeSettlement with the recipient addresses.
- 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..."
}
}
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 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) |
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"
}
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 |
