Skip to main content
The KeystoneEscrow contract is a minimal lock/release/rollback mechanism deployed on every chain where settlements occur. It holds deposits until the SettlementCoordinator instructs release or rollback. A lock box, not a bank. The escrow contract does not calculate interest, manage collateral ratios, handle liquidations, or hold assets beyond the settlement window. It has no lending logic of any kind.

​
Functions

​
registerSettlement()

Registers expected deposits for a settlement. Called by the settlement engine after compliance clears. 
function registerSettlement(
    bytes32 settlementId,
    Leg[] legs,
    uint256 timeoutAt
) external
Each leg specifies:
  • Token address (the ERC-20 or ERC-3643 token to deposit)
  • Amount expected
  • Depositor address (must match the registered party)
Only the registered depositor for each leg can deposit. This prevents a malicious actor from creating a settlement and tricking an unrelated party into depositing.

​
depositLeg()

Deposits tokens for a specific leg. Called by the settlement party (or their custody provider like Fireblocks). 
function depositLeg(
    bytes32 settlementId,
    uint256 legIndex
) external
The contract validates:
  1. Settlement is registered and not in a terminal state
  2. msg.sender matches the registered depositor for this leg
  3. The leg has not already been deposited
  4. Token allowance is sufficient
Emits: LegDeposited(bytes32 settlementId, uint256 legIndex, address depositor, uint256 amount)

​
executeSettlement()

Releases all deposits to their intended recipients. Called by the coordinator (directly or via LayerZero) after the atomicity gate confirms all legs are deposited. 
function executeSettlement(bytes32 settlementId) external
In a single transaction:
  • Tokens from the seller’s leg go to the buyer’s wallet
  • Tokens from the buyer’s leg go to the seller’s wallet
For ERC-3643 tokens, the contract uses forcedTransfer() which allows the token’s transfer agent to move tokens between whitelisted addresses. Emits: SettlementExecuted(bytes32 settlementId)

​
rollbackSettlement()

Returns all deposited tokens to their original depositors. Called by the coordinator on failure or timeout. 
function rollbackSettlement(bytes32 settlementId) external
Each depositor receives back exactly what they deposited. No fees, no penalties. Emits: SettlementRolledBack(bytes32 settlementId)

​
claimTimeout()

Permissionless timeout claim. Anyone can call this after the settlement deadline to return deposits. 
function claimTimeout(bytes32 settlementId) external
Validates block.timestamp >= timeoutAt and returns all deposits to their original owners. This is a safety mechanism ensuring funds are never locked indefinitely. Emits: SettlementTimedOut(bytes32 settlementId)

​
View functions

function allLegsDeposited(bytes32 settlementId) external view returns (bool)
function getLegStatus(bytes32 settlementId, uint256 legIndex) external view returns (LegStatus)

​
Events

EventWhenData
LegDepositedA party deposits tokens for a legsettlementId, legIndex, depositor, amount
SettlementExecutedAtomic swap completedsettlementId
SettlementRolledBackAll deposits returned on failuresettlementId
SettlementTimedOutTimeout triggered, deposits returnedsettlementId
The Event Indexer monitors these events to update the database and trigger settlement advancement (e.g. when all deposits are confirmed).

​
Token standards

StandardSupportRelease mechanism
ERC-20FullStandard transfer()
ERC-3643FullforcedTransfer() via transfer agent role
ERC-3643 is the institutional security token standard. It requires whitelisted addresses and transfer agent authorization. The escrow contract holds the transfer agent role, allowing it to move compliant tokens between whitelisted parties.

​
Cross-chain mode

In Phase 2 (cross-chain), escrow contracts on remote chains receive instructions from the SettlementCoordinator via LayerZero: The escrow contract on each chain operates independently. It only communicates with the coordinator via LayerZero messages.

​
Security properties

  • No admin keys: No KeyStone-controlled withdrawal function
  • No upgrade authority: Escrow contracts are designed to be immutable
  • Depositor validation: Only the registered party can deposit for each leg
  • Atomic execution: All legs release in one transaction or none do
  • Permissionless timeout: Anyone can recover funds after the deadline
  • No custody risk: KeyStone never controls deposited funds