Skip to content

LP-0006.md

Latest commit

 

History

History
202 lines (146 loc) · 18.4 KB

LP-0006.md

File metadata and controls

202 lines (146 loc) · 18.4 KB

LP-0006: Atomic Swap with LEZ [DRAFT]

Status: Draft - pending LEZ timelock feature, Logos Delivery module, and Logos Chat module Logos Circle: N/A

Overview

The Logos ecosystem already has a working ETH–LEZ atomic swap using Hash Time-Locked Contracts (eth-lez-atomic-swaps). This prize is for a unified atomic swap application that supports trustless swaps between LEZ and all three of the following chains:

  • Bitcoin — using Schnorr adaptor signatures and Taproot key-path spends (no custom scripts, swap indistinguishable from a normal payment).
  • Monero — using Ed25519 adaptor signatures with cross-curve Discrete Log Equality (DLEQ) proofs (the h4sh3d/COMIT protocol, proven on Bitcoin–Monero mainnet).
  • Ethereum — using HTLCs or adaptor signatures against an Ethereum RPC endpoint.

The LEZ side is implemented as a Risc0 guest program (Rust) that locks funds contingent on revealing a secret (adaptor secret, hash preimage, or DLEQ proof, depending on the protocol).

The application follows a maker/taker model: the maker acts as a liquidity provider, configuring which trading pairs and prices they support. The maker advertises prices over Logos Delivery, and maker-taker negotiation happens over Logos Chat — no central infrastructure is used. The maker software must support pricing from both a local configuration (e.g., static prices for testing) and an external source (e.g., a REST API), with the specific external integration left to the developer.

Note: This prize is currently in Draft status because the following dependencies are not yet available:

  • LEZ timelock: LEZ does not yet support on-chain timelocks.
  • Logos Delivery module: Required for makers to advertise prices and trading pairs.
  • Logos Chat module: Required for maker-taker negotiation and swap coordination.

The prize will open once all three are available.

Motivation

Enabling trustless swaps between LEZ and widely-held digital assets — without custodians, bridges, or wrapped tokens — is a prerequisite for meaningful DeFi liquidity in the Logos ecosystem. Different chains present different cryptographic challenges:

  • Bitcoin: HTLCs work but have drawbacks (non-standard script, on-chain preimage links the swap legs, identifiable as an atomic swap). Adaptor signatures solve all three — the Bitcoin transaction is a plain Taproot spend, no preimage appears on-chain, and the two legs are cryptographically unlinked.
  • Monero: No scripting system, so neither HTLCs nor standard adaptor signatures apply directly. The established solution combines Ed25519 adaptor signatures with cross-curve DLEQ proofs to atomically transfer a Monero spend key share.
  • Ethereum: The existing ETH–LEZ HTLC swap provides a reference, but participants may propose improved approaches (e.g., adaptor signatures, more efficient gas usage).

A competitive prize is the right mechanism because the protocol design, LEZ escrow construction, and cross-chain coordination all admit multiple valid approaches with meaningful trade-offs.

Security & Reliability Assumptions

The following assumptions underpin the security and reliability of the atomic swap protocol. Submissions must clearly document how their implementation relies on each assumption and what happens if an assumption is violated.

Security Assumptions

  • Trustlessness: Neither party trusts the other. The protocol must guarantee that a rational adversary cannot steal funds — either both legs of the swap complete, or both are refunded.
  • No centralised intermediaries: No trusted third party, relay, or centralised service is involved in swap execution, price discovery, or coordination. All communication uses Logos Delivery and Logos Chat.
  • Cryptographic hardness: The security of adaptor signatures (Bitcoin), cross-curve DLEQ proofs (Monero), and hash-lock constructions (Ethereum) relies on the hardness of the discrete logarithm problem on secp256k1 and Ed25519. Submissions must state which cryptographic assumptions they depend on.
  • On-chain finality: Each chain's finality model is assumed to hold. Submissions must document the number of confirmations required on each chain before a swap leg is considered final, and the risk of chain reorganisations.
  • Timelock safety margin: Timelocks must be set with sufficient margin to account for block time variance, network congestion, and clock drift. Submissions must document their timelock parameter choices and the rationale.
  • Key management: Private keys and adaptor secrets are assumed to be stored securely on each party's local machine. The protocol's security does not extend to compromised keys.

Reliability Assumptions

  • Network availability: Both parties must be online during the active swap window. Submissions must document what happens if a party goes offline mid-swap (expected behaviour: the counterparty can reclaim funds after the timelock expires).
  • Node liveness: Each party is assumed to have access to a functioning node for each relevant chain (Bitcoin, Monero, Ethereum, LEZ). Submissions must document graceful degradation if a node becomes temporarily unreachable (e.g., retry logic, swap state persistence).
  • Swap state persistence: The swap coordinator must persist swap state locally so that incomplete swaps can be resumed after a crash or restart. Loss of swap state before the timelock expires must not lead to loss of funds.
  • Concurrent swap isolation: Multiple in-flight swaps must not interfere with each other. Each swap must maintain independent state, escrow, and timelock tracking.
  • Logos Delivery & Chat availability: Price advertisements and negotiation messages depend on the Logos Delivery and Logos Chat modules being available. Submissions must document behaviour when these services are temporarily unreachable (e.g., retry, buffering, degraded mode).

Success Criteria

Functionality

  • No central infrastructure: The application must not depend on any centralised server or service to operate. All communication between maker and taker uses the Logos stack (see below).
  • Trustless swaps between LEZ and all three chains (Bitcoin, Monero, Ethereum) can be completed without custodians, bridges, or wrapped tokens. The Ethereum side must use the Logos Ethereum module for Ethereum interactions.
  • The swap protocol is appropriate for each chain's capabilities (adaptor signatures for Bitcoin/Taproot, DLEQ proofs for Monero, HTLCs or adaptor signatures for Ethereum).
  • The LEZ escrow program correctly enforces release of funds upon the required proof (adaptor secret, DLEQ proof, or hash preimage) and supports refund after timelock expiry (see Security & Reliability Assumptions for timelock details).
  • The two legs of each swap are atomic: either both complete or both refund. There is no state where one party receives funds and the other does not.
  • Token support on LEZ: Swaps support both the native LEZ token and custom tokens issued via the LEZ token program, using Associated Token Accounts (ATAs).
  • Token support on Ethereum: Swaps support both native ETH and ERC-20 tokens.
  • Maker/taker model: The maker operates as a liquidity provider. The maker software allows configuration of supported trading pairs and prices. The maker advertises available pairs and prices over Logos Delivery (the Logos storage/data availability layer). Maker-taker negotiation and swap coordination messages are exchanged over Logos Chat (the Logos messaging layer).
  • Maker pricing: The maker software supports two pricing modes: (1) local configuration (static prices set via config file or CLI, useful for testing) and (2) external price feed (fetching prices from an external service, e.g., a REST API). The specific external integration is left to the developer, but the architecture must support pluggable price sources.
  • The maker is deployable as a headless service with all necessary functionality (pair/price configuration, external price feed, liquidity management, swap execution, monitoring) — no GUI required for operation.
  • At least 5 complete swaps are executed per chain on testnets, involving at least 3 distinct counterparty pairs outside the submitting team.

Usability

  • A CLI is provided for both maker and taker roles. The maker CLI covers the full swap lifecycle. The taker CLI may have limited functionality if a GUI is the primary taker interface.
  • A GUI (Logos Basecamp app) is provided for both maker and taker roles, with local build instructions, downloadable assets, and loadable in Logos app (Basecamp).
  • A module/SDK is provided that can be used to build Logos modules for interacting with the swap system.
  • An IDL is provided for the LEZ escrow program(s), using the SPEL framework.

Reliability

  • Graceful degradation: If a chain-specific dependency is unavailable (e.g., no Monero node running, no Ethereum RPC configured), the application must still start and enable functionality for the remaining chains. Unavailable chains are clearly reported to the user.
  • Swap state is persisted locally so that incomplete swaps can be resumed after a crash or restart without loss of funds.
  • Multiple in-flight swaps do not interfere with each other — each swap maintains independent state, escrow, and timelock tracking.

Performance

  • Document the compute unit (CU) cost of each LEZ escrow operation (lock, release, refund) on LEZ devnet/testnet. Note: LEZ's per-transaction compute budget may change during testnet.

Supportability

  • The program is deployed and tested on LEZ testnet 0.2.
  • End-to-end integration tests run against a LEZ sequencer (standalone mode) and are included in CI.
  • CI must be green on the default branch.
  • A reference integration is delivered for each chain: working demos of complete swaps on Bitcoin testnet, Monero stagenet, Ethereum Sepolia, and LEZ testnet 0.2.
  • Full documentation and a clean public repository are delivered, including deployment steps, program addresses, and step-by-step instructions for interacting with the program via CLI and Basecamp app. Documentation must include clear prerequisites for each chain (e.g., Bitcoin Core node URL, Monero node + wallet RPC URLs, Ethereum Web3 RPC URL, LEZ testnet access) and step-by-step setup instructions for both maker and taker sides.
  • A reproducible end-to-end demo script is provided for each supported chain and works against a real local sequencer with RISC0_DEV_MODE=0.
  • Recorded video demos are included in the submission; each recording must show terminal output (including proof generation) to confirm RISC0_DEV_MODE=0 was active.

Scope

In Scope

  • Bitcoin-side implementation: adaptor signatures using Schnorr/BIP-340 and Taproot key-path spends, including pre-signing and signature completion logic.
  • Monero-side implementation: key share generation, XMR locking to a combined address, spend key reconstruction, wallet sweep, and cross-curve DLEQ proof construction.
  • Ethereum-side implementation: HTLC or adaptor signature contracts for ETH↔LEZ and ERC-20↔LEZ swaps, using the Logos Ethereum module for Ethereum interactions.
  • LEZ escrow program(s) (Rust, Risc0) that lock funds (native token or custom tokens via ATA) contingent on the appropriate cryptographic proof for each chain, with timelock-based refund.
  • Maker software: headless-deployable service with pair/price configuration, external price feed integration, liquidity advertisement, and full swap execution.
  • Taker software: discovery of maker offers, swap initiation, monitoring, and claim/refund.
  • CLI (full functionality for maker, may be limited for taker), GUI (both roles), and module/SDK for programmatic integration.
  • Reference integrations on Bitcoin testnet, Monero stagenet, Ethereum Sepolia, and LEZ testnet 0.2, demonstrating complete swaps.
  • Documentation covering: protocol design for each chain, LEZ escrow design, cross-chain atomicity argument, timelock handling, security assumptions, and known limitations.

Out of Scope

  • Lightning Network integration or multi-hop/routed swaps.
  • Ongoing maintenance or security audits beyond initial delivery. Follow-up prizes may cover testnet 0.3 compatibility, mainnet deployment, and ongoing maintenance — see Potential for Subsequent λPrizes.

Infrastructure & Dependencies

Participants must run or have access to the following infrastructure for all three target chains:

Bitcoin

  • A Bitcoin Core full node or access to a Bitcoin testnet node (e.g., running bitcoind locally with testnet=1).
  • A Bitcoin wallet capable of creating and signing Taproot (P2TR) transactions (e.g., Bitcoin Core 22+, or a library like rust-bitcoin with Taproot support).
  • Familiarity with BIP-340 (Schnorr) and BIP-341 (Taproot).

Monero

  • A Monero full node running on stagenet (monerod --stagenet), or access to a public stagenet node.
  • A Monero wallet RPC instance (monero-wallet-rpc --stagenet) for programmatic wallet operations.
  • Stagenet XMR (available from Monero stagenet faucets).
  • Familiarity with Monero's key structure (spend key, view key) and transaction construction.

Ethereum

  • Access to an Ethereum RPC endpoint (e.g., a local node via geth or reth, or a provider such as Infura, Alchemy, or a public Sepolia RPC).
  • Sepolia ETH for testnet deployment (available from Sepolia faucets).
  • Familiarity with Solidity smart contracts and tooling (Foundry, Hardhat, or similar).

LEZ (all targets)

  • The application must work with LEZ testnet 0.2.
  • Access to the LEZ testnet and LEZ CLI tooling.
  • Rust toolchain and Risc0 development environment for building LEZ programs.
  • Familiarity with the Logos Execution Zone architecture and the eth-lez-atomic-swaps reference implementation.

Prize Structure

  • Total Prize: $TBD
  • Effort: XL

Eligibility

Open to any individual or team. Submissions must be original work. Teams must hold the rights to all submitted code and agree to license it under MIT and Apache-2.0.

Submission Requirements

  • Public repository with Bitcoin, Monero, and Ethereum swap implementations, LEZ escrow program(s), and coordination tooling under MIT or Apache-2.0.
  • LEZ escrow program deployed on LEZ testnet 0.2 with a verified program ID.
  • Demo videos — for each supported chain (Bitcoin, Monero, Ethereum), three separate narrated recordings in which the builder explains what they built and why, walks through the architecture and key implementation decisions, and demonstrates a complete end-to-end swap with LEZ. A silent screencast is not sufficient (see demo requirements). Each chain must show:
    1. A happy path swap: both parties complete the protocol successfully.
    2. A refund/timeout path swap: one party abandons the protocol and the other recovers their funds via the timelock refund.
    3. A concurrent swap demo: two or more swaps executing in parallel, demonstrating that the system handles multiple in-flight swaps correctly.
  • Write-up covering: protocol design for each chain, LEZ escrow design, cross-chain atomicity argument, timelock handling, security assumptions, known limitations, and integration instructions.
  • FURPS self-assessment as part of the solution (see solution template).

Evaluation Process

Submissions are evaluated first-come-first-served against the success criteria. The first submission that satisfies all criteria wins.

Evaluators will independently clone the repository and run the demo script from a clean environment; the script must succeed without modification. Evaluators may also ask technical follow-up questions to verify authorship and understanding of the implementation.

The following policies apply to all prizes (see evaluation policies):

  • Submissions: each builder (or team) is allowed a maximum of 3 submissions per prize, with at most one submission/review per week.
  • Feedback: initial evaluation feedback is limited to a pass/fail indication against the success criteria.

Resources

General

Bitcoin

Monero

Potential for Subsequent λPrizes

  • Testnet 0.3 compatibility: If LEZ testnet 0.3 introduces breaking changes, a follow-up prize may be opened to update the atomic swap implementation for compatibility.
  • Mainnet deployment: A subsequent prize may target mainnet deployment of the atomic swap application, with adoption-related success criteria (e.g., volume, number of unique users, liquidity thresholds).