Skip to main content

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us