Atomic Swaps

Learn how 1inch implements trustless cross-chain token swaps using atomic swap technology

What are Atomic Swaps?

Atomic swaps enable trustless token exchanges between different blockchains without intermediaries. The “atomic” property ensures that either both parties receive their tokens, or neither does - there is no possibility of only one party being paid.

The 1inch Cross Chain SDK implements atomic swaps using a combination of:

• Hash-locked escrows on both chains
• Time-locked refund mechanisms for safety
• Cryptographic secrets for authorization

How Cross-Chain Swaps Work

A cross-chain swap in the 1inch SDK follows this workflow:

Step-by-Step Process

1. Order Creation: Maker creates a cross-chain order specifying:

   • Source token and amount
   • Destination token and amount
   • Hash-lock derived from secret(s)
   • Time-locks for each stage

2. Escrow Deployment: Resolver deploys escrows on both chains with safety deposits

3. Secret Revelation: Maker reveals the secret after verifying escrow deployments

4. Withdrawal: Resolver uses the secret to withdraw from both escrows

Security Guarantees

The SDK provides multiple layers of security:

Atomicity: The swap either completes fully or can be cancelled and refunded on both chains.

Hash-Lock Protection

Funds are locked using a cryptographic hash. Only someone with the original secret can unlock them:

// From hash-lock.ts:17-24
public static hashSecret(secret: string): string {
    assert(
        isHexBytes(secret) && getBytesCount(secret) === 32n,
        'secret length must be 32 bytes hex encoded'
    )
    return keccak256(secret)
}

Safety Deposits

Resolvers must lock safety deposits in both source and destination escrows. This ensures:

• Resolvers are incentivized to complete swaps
• Users can claim safety deposits if resolvers fail
• Economic penalties for malicious behavior

// From escrow-extension.ts:58-59
assert(srcSafetyDeposit <= UINT_128_MAX, 'srcSafetyDeposit exceeds max')
assert(dstSafetyDeposit <= UINT_128_MAX, 'dstSafetyDeposit exceeds max')

Time-Locked Stages

Each escrow progresses through time-locked stages:

Source Chain:

| Finality Lock | Private Withdrawal | Public Withdrawal | Private Cancellation | Public Cancellation |
^deployedAt

Destination Chain:

| Finality Lock | Private Withdrawal | Public Withdrawal | Private Cancellation |
^deployedAt

See Time Locks API documentation for details.

Timeout and Refund Mechanisms

Always verify escrow addresses and parameters before revealing secrets. Once revealed, secrets cannot be taken back.

Cancellation Windows

If a swap doesn’t complete, funds can be refunded during cancellation periods:

1. Private Cancellation: Only the maker can cancel and retrieve funds
2. Public Cancellation (source chain only): Anyone can trigger cancellation

Rescue Delay

The default rescue delay is 7 days:

// From time-locks.ts:21
static DEFAULT_RESCUE_DELAY = 604800n // 7 days

Refund Process

// From Resolver.sol:108-113
function cancel(
    IEscrow escrow,
    IBaseEscrow.Immutables calldata immutables
) external {
    escrow.cancel(immutables)
}

The cancel function can be called during the appropriate cancellation window to retrieve:

• Original token amount
• Safety deposit (if resolver failed to complete)

Example: Creating an Atomic Swap Order

import { SDK, HashLock, NetworkEnum } from '@1inch/cross-chain-sdk'
import { randomBytes } from 'crypto'

// Generate secret for the swap
const secret = '0x' + randomBytes(32).toString('hex')
const hashLock = HashLock.forSingleFill(secret)

// Create order
const { hash, order } = await sdk.createOrder(quote, {
  walletAddress,
  hashLock,
  preset: 'fast',
  source: 'my-app'
})

// Wait for escrow deployment
const secretsToShare = await sdk.getReadyToAcceptSecretFills(hash)

// Verify escrow addresses before revealing!
if (secretsToShare.fills.length > 0) {
  // Only reveal after verification
  await sdk.submitSecret(hash, secret)
}

The SDK handles most complexity internally. You only need to manage secret generation and revelation timing.

Best Practices

1. Always verify escrow deployments before revealing secrets
2. Store secrets securely until ready to reveal
3. Monitor order status to track swap progress
4. Set appropriate time-locks based on chain finality times
5. Use sufficient safety deposits to incentivize proper resolver behavior

Related Concepts

• Hash Locks - Cryptographic locking mechanism
• Escrows - Smart contract escrow implementation
• Secrets Management - How to safely handle secrets