Skip to main content

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.

KeyStone supports settlement where the two legs live on different chains. The bond can be on Ethereum while the USDC payment is on Avalanche. Assets never bridge - they stay on their native chain, with LayerZero messaging coordinating between escrow contracts.

​
How it works

​
Key properties

  • Assets never bridge. The bond stays on Ethereum. The USDC stays on Avalanche. No wrapping, no synthetic representations.
  • Both legs settle or neither does. The atomicity gate on the coordinator chain verifies all locks before dispatching any releases.
  • Independent deposits. Neither party deposits first. Both deposit independently to their local escrow using their deposit secret. This eliminates the “who goes first” problem.
  • Fully autonomous. After compliance clears, the contracts handle deposits, execution, and finalization without KeyStone in the loop.
  • Permissionless timeout. If either deposit fails or the deadline passes, anyone can trigger timeout. Deposits are returned on all chains.

​
Settlement flow

​
1. Bilateral instruction submission

Both parties submit instructions as normal. The chain_id field in each party’s details and legs indicates which chain their assets are on: 
# Seller (bond on Ethereum, chain_id: 1)
curl -X POST https://api.keystoneos.xyz/v1/instructions \
  -H "Authorization: Bearer $SELLER_TOKEN" \
  -d '{
    "template_slug": "cross-chain-dvp",
    "role": "seller",
    "party": {
      "wallet_address": "0xSellerOnEthereum...",
      "chain_id": 1
    },
    "legs": [
      {
        "instrument_id": "0xBondTokenAddress",
        "quantity": "100",
        "direction": "deliver",
        "chain_id": 1
      },
      {
        "instrument_id": "0xUSDCOnAvalanche",
        "quantity": "50000",
        "direction": "receive",
        "chain_id": 43114
      }
    ]
  }'

# Buyer (USDC on Avalanche, chain_id: 43114)
curl -X POST https://api.keystoneos.xyz/v1/instructions \
  -H "Authorization: Bearer $BUYER_TOKEN" \
  -d '{
    "trade_reference": "KS-abc123...",
    "template_slug": "cross-chain-dvp",
    "role": "buyer",
    "party": {
      "wallet_address": "0xBuyerOnAvalanche...",
      "chain_id": 43114
    },
    "legs": [
      {
        "instrument_id": "0xBondTokenAddress",
        "quantity": "100",
        "direction": "receive",
        "chain_id": 1
      },
      {
        "instrument_id": "0xUSDCOnAvalanche",
        "quantity": "50000",
        "direction": "deliver",
        "chain_id": 43114
      }
    ]
  }'

​
2. On-chain creation and compliance

After matching, the settlement is created on the SettlementCoordinator. KeyStone runs compliance screening and attests results to the ComplianceRegistry.

​
3. Parties deposit to their local escrow

Each party deposits to the escrow contract on their own chain using their deposit_secret (from the settlement response). The seller calls depositLeg on the Ethereum escrow with their secret. The buyer calls depositLeg on the Avalanche escrow with their secret. Parties use their own custody provider to sign the transactions.

​
4. LayerZero messaging

Each escrow contract sends a lock confirmation to the SettlementCoordinator via LayerZero. The coordinator collects confirmations from all chains.

​
5. Atomicity gate and release

The coordinator checks allLegsDeposited(). This only returns true when ALL legs on ALL chains have confirmed deposits. The coordinator then calls executeSettlement(settlementId, recipients[]) on all escrow contracts via LayerZero, revealing recipient addresses only at execution time.
  • Bond tokens on Ethereum go to the buyer’s Ethereum address
  • USDC on Avalanche goes to the seller’s Avalanche address

​
Timeout and rollback

If any deposit is missing when the deadline arrives: Timeout is permissionless. Any party can trigger it after the deadline, ensuring funds are never locked indefinitely regardless of KeyStone’s availability.

​
Supported chains

Cross-chain settlement is a Phase 2 feature. Phase 1 operates on a single chain (Sepolia testnet, then L2 mainnet). The architecture supports any EVM-compatible chain with LayerZero integration. The coordinator chain can be any EVM chain - it is not tied to a specific blockchain.
Cross-chain settlement requires LayerZero messaging, which adds approximately 100,000 gas per message (4 messages for a 2-chain settlement: 2 lock confirmations + 2 release dispatches).