diff --git a/RFPs/RFP-003-atomic-swaps.md b/RFPs/RFP-003-atomic-swaps.md index 9326193..e447dc8 100644 --- a/RFPs/RFP-003-atomic-swaps.md +++ b/RFPs/RFP-003-atomic-swaps.md @@ -14,10 +14,15 @@ category: Applications & Integrations ## 🧭 Overview Build a unified atomic swap application that enables trustless, non-custodial exchanges -between LEZ and three major chains: **Bitcoin**, **Monero**, and **Ethereum**. The LEZ -side is implemented as a Risc0 guest program that locks funds contingent on the appropriate cryptographic proof for each chain. A reference implementation for ETH–LEZ swaps already exists ([eth-lez-atomic-swaps](https://github.com/logos-co/eth-lez-atomic-swaps)); -this RFP extends the work to Bitcoin and Monero, and delivers a complete, production-ready -swap application. +between LEZ and four major chains: **Bitcoin**, **Monero**, **Ethereum**, and +**Zcash** (transparent pool). The LEZ side is implemented as a Risc0 guest program +that locks funds contingent on the appropriate cryptographic proof for each chain. +A reference implementation for ETH–LEZ swaps already exists +([eth-lez-atomic-swaps](https://github.com/logos-co/eth-lez-atomic-swaps)); +this RFP extends the work to Bitcoin, Monero, and Zcash, and delivers a complete, +production-ready swap application. Zcash shielded-pool (Sapling / Orchard) swaps are +explicitly out of scope — the cryptographic state of the art does not yet provide a +drop-in design (see [Appendix: Zcash Atomic Swap Primitives](../appendix/zcash-atomic-swap-primitives.md)). The application uses a **maker/taker model**: the maker acts as a liquidity provider, advertising offers over **Logos Delivery** and coordinating swaps over **Logos Chat** — @@ -39,7 +44,9 @@ with Taproot key-path spends solve this, making swaps indistinguishable from nor payments. Monero has no scripting system at all, requiring cross-curve DLEQ proofs to achieve atomicity. Ethereum provides the most flexibility and an existing reference, but the implementation must integrate with the Logos Ethereum module and meet the same -trustlessness guarantees as the other chains. +trustlessness guarantees as the other chains. Zcash transparent inherits Bitcoin script +unchanged and supports HTLC-based swaps via [BIP-199](https://github.com/bitcoin/bips/blob/master/bip-0199.mediawiki); +adaptor-signature variants are a stretch goal for cross-chain unlinkability. Delivering this application — with its fully decentralised coordination via Logos Delivery and Logos Chat — demonstrates that the Logos stack can support real-world, multi-chain @@ -66,33 +73,42 @@ for the maturity of those modules and a high-visibility proof point for ecosyste on-chain scripting. 4. Trustless swaps between LEZ and **Ethereum** are supported using HTLCs or adaptor signatures. Ethereum interactions must use the **Logos Ethereum module**. -5. The LEZ escrow program (Rust, Risc0) locks funds contingent on the appropriate +5. Trustless swaps between LEZ and **Zcash transparent (`t1...`) addresses** are + supported using BIP-199-style HTLCs (`OP_IF / OP_SHA256 / OP_CLTV / OP_CHECKSIG` + on the Zcash side, mirrored on the LEZ side). The Zcash refund deadline must + strictly succeed the LEZ refund deadline by a margin documented to cover + worst-case Zcash confirmation latency. ECDSA adaptor signatures (Lloyd Fournier + construction) are an acceptable alternative to HTLCs and are encouraged for + cross-chain unlinkability. Zcash shielded-pool (Sapling / Orchard) swaps are + **out of scope** for this RFP — see [Appendix: Zcash Atomic Swap Primitives](../appendix/zcash-atomic-swap-primitives.md) + for the rationale. +6. The LEZ escrow program (Rust, Risc0) locks funds contingent on the appropriate cryptographic proof for each chain (adaptor secret, DLEQ proof, or hash preimage) and releases them upon valid proof submission. Funds are refunded to the depositor after the timelock expires. -6. The two legs of each swap are atomic: either both complete or both refund. No +7. The two legs of each swap are atomic: either both complete or both refund. No state exists where one party receives funds and the other does not. -7. Swaps on LEZ support both the native LEZ token and custom tokens issued via the +8. Swaps on LEZ support both the native LEZ token and custom tokens issued via the LEZ token program, using Associated Token Accounts (ATAs). -8. Swaps on Ethereum must support both **native ETH** and **ERC-20 tokens**. Both +9. Swaps on Ethereum must support both **native ETH** and **ERC-20 tokens**. Both asset types must be fully supported in the Ethereum escrow contract — partial support (e.g., ETH only) is not acceptable. -9. The maker software supports two pricing modes: (1) **local configuration** — static - prices set via config file or CLI, suitable for testing; (2) **external price feed** - — prices fetched from an external source (e.g., a REST API). The architecture must - support pluggable price sources; the specific external integration is left to the - developer. -10. The maker is deployable as a **headless daemon** covering pair and price +10. The maker software supports two pricing modes: (1) **local configuration** — static + prices set via config file or CLI, suitable for testing; (2) **external price feed** + — prices fetched from an external source (e.g., a REST API). The architecture must + support pluggable price sources; the specific external integration is left to the + developer. +11. The maker is deployable as a **headless daemon** covering pair and price configuration, external price feed integration, liquidity advertisement, swap execution, and monitoring — the daemon must be fully operable via the maker CLI without a GUI. #### Usability -1. Provide a dedicated SDK per trading pair (LEZ–BTC, LEZ–XMR, LEZ–ETH) that can - be used to build Logos modules for interacting with that pair's swap protocol. - Each SDK must expose the full swap lifecycle (offer discovery, negotiation, - escrow creation, claim, and refund) for its respective chain. +1. Provide a dedicated SDK per trading pair (LEZ–BTC, LEZ–XMR, LEZ–ETH, LEZ–ZEC) + that can be used to build Logos modules for interacting with that pair's swap + protocol. Each SDK must expose the full swap lifecycle (offer discovery, + negotiation, escrow creation, claim, and refund) for its respective chain. 2. Provide a **maker daemon** — a long-running headless process that manages liquidity advertisement, price feeds, incoming swap requests, and swap execution without human interaction. A systemd unit file must be provided for running the @@ -124,6 +140,10 @@ for the maturity of those modules and a high-visibility proof point for ecosyste use the existing Logos Ethereum module; the documentation must explain how to point the module at a chosen RPC endpoint (self-hosted or third-party provider). +11. Provide step-by-step documentation for setting up a **Zcash node** (`zcashd` + or `zebrad`) on testnet, including transparent wallet creation and obtaining + testnet funds. Documentation must cover both self-hosted and public testnet + node options. #### Reliability @@ -176,12 +196,12 @@ for the maturity of those modules and a high-visibility proof point for ecosyste 7. The write-up covers: protocol design for each chain, LEZ escrow design, cross-chain atomicity argument, timelock handling, security assumptions, and known limitations. -8. Each per-pair SDK (LEZ–BTC, LEZ–XMR, LEZ–ETH) must include full API +8. Each per-pair SDK (LEZ–BTC, LEZ–XMR, LEZ–ETH, LEZ–ZEC) must include full API documentation: all public types, functions, and error types, with usage examples covering the complete swap lifecycle (offer discovery, negotiation, escrow creation, claim, and refund). 9. Submit a [doc packet](https://github.com/logos-co/logos-docs/issues/new?template=doc-packet.yml) - for each per-pair SDK (LEZ–BTC, LEZ–XMR, LEZ–ETH), covering the developer + for each per-pair SDK (LEZ–BTC, LEZ–XMR, LEZ–ETH, LEZ–ZEC), covering the developer integration journey for that swap protocol. 10. Submit a [doc packet](https://github.com/logos-co/logos-docs/issues/new?template=doc-packet.yml) for the maker CLI and a separate one for the taker CLI, each covering the @@ -191,7 +211,7 @@ for the maturity of those modules and a high-visibility proof point for ecosyste #### + (Demos) -1. For **each supported chain** (Bitcoin, Monero, Ethereum), three recorded demo +1. For **each supported chain** (Bitcoin, Monero, Ethereum, Zcash), three recorded demo videos must be submitted: - **Happy path**: both parties complete the swap successfully end-to-end. - **Refund/timeout path**: one party abandons the protocol and the other recovers @@ -213,6 +233,8 @@ for the maturity of those modules and a high-visibility proof point for ecosyste - Bitcoin: Taproot/P2TR transaction construction, BIP-340/BIP-341 - Monero: key structure (spend/view keys), transaction construction, stagenet - Ethereum: Solidity smart contracts, Foundry or Hardhat, ERC-20 interactions +- Zcash: transparent transaction construction, BIP-199 HTLCs, `zcashd`/`zebrad` + testnet - Distributed systems: swap state machines, crash recovery, concurrent coordination @@ -255,6 +277,16 @@ All code must be released under the **MIT+Apache2.0 dual License**. - Logos Ethereum module — use for all Ethereum interactions +### Zcash + +- [Appendix: Zcash Atomic Swap Primitives](../appendix/zcash-atomic-swap-primitives.md) — feasibility matrix, why shielded is out of scope, prior-art comparison +- [BIP-199: Hashed Time-Locked Contract transactions](https://github.com/bitcoin/bips/blob/master/bip-0199.mediawiki) — canonical HTLC layout used for transparent ZEC swaps +- [ZIP-203: Transaction Expiry](https://zips.z.cash/zip-0203) — `nExpiryHeight` semantics +- [ZIP-202: Version 3 Transaction Format for Overwinter](https://zips.z.cash/zip-0202) +- [`zcash/zcash` (`zcashd`)](https://github.com/zcash/zcash) and [`ZcashFoundation/zebra` (`zebrad`)](https://github.com/ZcashFoundation/zebra) — full nodes +- [`librustzcash`](https://github.com/zcash/librustzcash) — Rust transaction-construction crates +- [Zwap forum thread](https://forum.zcashcommunity.com/t/zwap-unlinkable-cross-chain-atomic-swaps/55104) — most active 2025 prior-art for transparent ZEC atomic swaps + ## ✏️ How to Apply diff --git a/appendix/zcash-atomic-swap-primitives.md b/appendix/zcash-atomic-swap-primitives.md new file mode 100644 index 0000000..223fbfc --- /dev/null +++ b/appendix/zcash-atomic-swap-primitives.md @@ -0,0 +1,194 @@ +# Zcash Atomic Swap Primitives + +What's needed for a non-custodial atomic swap between LEZ and Zcash, what +Zcash exposes today, and why the answer differs sharply between Zcash's +transparent and shielded pools. + +## Two pools, two answers + +Zcash has three on-chain pools. Their swap-relevant capabilities differ: + +| Pool | Address prefix | Scripting | Spend authorization | Curve | +|------|----------------|-----------|---------------------|-------| +| Transparent | `t1...` | Bitcoin script (full subset) | secp256k1 ECDSA | secp256k1 | +| Sapling | `zs1...` | None | RedJubjub (Schnorr-like RedDSA) | Jubjub | +| Orchard | `u1...` / `o1...` | None | RedPallas (Schnorr-like RedDSA) | Pallas | + +The transparent pool is a near-clone of Bitcoin and supports HTLC-based +atomic swaps today via [BIP-199](https://github.com/bitcoin/bips/blob/master/bip-0199.mediawiki). +The shielded pools (Sapling, Orchard) have no on-chain scripting at all, +and as of May 2026 there is no production-ready atomic swap to or from +either of them. + +## Transparent pool — implementable today + +Zcash transparent inputs, outputs, and scripts behave as in Bitcoin. The +opcodes relevant to swaps — `OP_IF / OP_ELSE / OP_ENDIF`, `OP_SHA256`, +`OP_HASH160`, `OP_CHECKLOCKTIMEVERIFY`, `OP_CHECKSEQUENCEVERIFY`, +`OP_CHECKSIG`, P2SH — all work. The canonical HTLC layout from BIP-199 +applies verbatim: + +``` +OP_IF + [HASHOP] OP_EQUALVERIFY OP_DUP OP_HASH160 +OP_ELSE + [TIMEOUTOP] OP_DROP OP_DUP OP_HASH160 +OP_ENDIF +OP_EQUALVERIFY +OP_CHECKSIG +``` + +Both legs of an HTLC swap reveal the same hash preimage on-chain. This +makes the two legs publicly linkable across chains — a privacy +limitation that adaptor-signature constructions explicitly fix. Zcash +transparent supports both: + +- **HTLC** — standard, well-trodden, mirrors the existing ETH-LEZ + reference implementation. +- **ECDSA adaptor signature** — Lloyd Fournier's construction with a + DLEQ proof. The on-chain footprint becomes an ordinary 2-of-2 spend + with no hash preimage broadcast. +- **ECDH multiplicative key aggregation** — a third route used by + [Zwap](https://forum.zcashcommunity.com/t/zwap-unlinkable-cross-chain-atomic-swaps/55104), + the most active 2025 Zcash atomic-swap project. Trades adaptor-sig + math for ECDH + a hash-preimage half-HTLC. Less private than full + adaptor-sig (still embeds a hash on both chains) but easier to + implement on chains that only verify standard ECDSA. + +For LEZ as the counterparty side, the LEZ-side primitives required — +SHA-256, BIP-340 Schnorr verification at the witness layer, block-height +and timestamp validity windows, AND-multisig witness sets — are all +present today. See the inline LEZ primitive status section in RFP-003 +for file citations. + +## Shielded pools — research-grade + +Sapling and Orchard expose no scripting. The only cryptographic hooks a +swap protocol can touch are: + +1. The **spendAuthSig** — a Schnorr-like signature over each spend. + Sapling uses RedJubjub on the Jubjub curve; Orchard uses RedPallas + on the Pallas curve. Both are instantiations of RedDSA. +2. The **transaction-level `nExpiryHeight`** field + ([ZIP-203](https://zips.z.cash/zip-0203)). Consensus rule: + "the transaction must be included in block N or earlier. Block N+1 + will be too late, and the transaction will be removed from the + mempool." The maximum is 499,999,999 (~1185 years). + +The critical limitation: **`nExpiryHeight` invalidates the *broadcast +attempt*, not the *funds*.** There is no shielded equivalent of +`OP_CHECKLOCKTIMEVERIFY` that creates a chain-enforced refund branch +on a deposited note. Refund must therefore be embedded in the +swap-protocol's signed messages (e.g. a pre-signed refund transaction +exchanged before funding), the same approach taken by +adaptor-signature swaps on Bitcoin Taproot. + +### The re-randomization wrinkle + +RedDSA's per-spend re-randomization makes shielded adaptor sigs harder +than the BIP-340 case. Every Sapling / Orchard spend signs with a +freshly randomized validating key: + +``` +rk = ak + [α]·G (α sampled by the spender, per spend) +spendAuthSig = RedDSA.Sign(rsk, sighash) where rsk = ask + α +``` + +A standard Schnorr adaptor pre-signature `(R', s')` works only if both +pre-signer and completer agree on `α` ahead of time, since `rk` enters +the sighash and must match between pre-sig and completion. The completer +also needs `α` to verify the standard Schnorr equation against the +on-chain `rk`. This is not a fundamental obstacle — the FROST/RedDSA +production stack already exposes a `RandomizePrivate(α, ask)` API for +working with randomized keys — but no published paper or code +specifically constructs an adaptor pre-signature against Sapling or +Orchard spend authorization. + +### Cross-curve binding + +A swap between LEZ (secp256k1) and Zcash shielded (Jubjub or Pallas) +needs the adaptor witness scalar to be valid on both curves. Group +orders differ. The standard mitigation, used by COMIT for XMR-BTC +swaps, is to attach a cross-curve DLEQ proof binding the same scalar +across both groups. For Pallas the pairing-friendly properties differ +from Ed25519, so the COMIT cross-curve DLEQ implementation is not a +drop-in port — additional cryptographic work would be required. + +### Best generic framework available + +The closest published framework is +[Universal Atomic Swaps](https://eprint.iacr.org/2021/1612) +(Thyagarajan, Malavolta, Moreno-Sánchez, IEEE S&P 2022), which proves a +generic protocol over "any chain that can verify signatures on +transactions" using adaptor signatures plus time-lock puzzles, with no +custom scripting required. The paper does not provide a Zcash-specific +instantiation. Adapting it to RedJubjub / RedPallas with re-randomization +is the open work. + +## What Maya Protocol is — and isn't + +[Maya Protocol](https://docs.mayaprotocol.com/mayachain-dev-docs/protocol-development/chain-clients/zcash) +went live with native ZEC support in May 2025 and is the most visible +production "Zcash swap" path. It is worth being precise about the trust +model: Maya is **not** an atomic swap. It is a vault network with +threshold-signed outbound transactions. Funds are custodied by the TSS +quorum of Maya node operators between the inbound and outbound legs. +Zcash side: transparent addresses (`t1...`) only, ECDSA, OP_RETURN +memos. + +Both atomic swaps and TSS vaults are valid product categories — vaults +give better UX and broader asset coverage; atomic swaps give stronger +trust guarantees. They should not be conflated when scoping a +non-custodial swap RFP. + +## Feasibility matrix + +| Pool | Construction | Required Zcash primitive | Trust model | Production status (2026-05) | +|---|---|---|---|---| +| Transparent | BIP-199 HTLC | OP_IF/ELSE, OP_SHA256/HASH160, OP_CLTV, OP_CHECKSIG, P2SH | Non-custodial atomic | Reference (ZBXCAT 2017); active in Zwap 2025 | +| Transparent | ECDSA adaptor signature (Fournier) | secp256k1 ECDSA + non-malleable `s`, refund via OP_CLTV | Non-custodial atomic | None Zcash-specific; well-tested for Bitcoin | +| Transparent | ECDH key aggregation (Zwap) | ECDSA + hash-preimage spend + OP_CLTV refund | Non-custodial atomic | Zwap alpha (Zcash + Ethereum) | +| Transparent | Vault / TSS routing | OP_RETURN memo + ECDSA | Custodial-via-TSS | Maya Protocol live since 2025-05 | +| Sapling | RedJubjub adaptor signature | Pre-sig on randomized `rk` over Jubjub; α-aware adaptor protocol; nExpiryHeight as broadcast-deadline only | Non-custodial atomic | None | +| Orchard | RedPallas adaptor signature | Same as Sapling on Pallas curve | Non-custodial atomic | None | +| Sapling / Orchard | HTLC | — | — | Not implementable: no on-chain scripting | +| Sapling / Orchard | Vault / TSS | RedDSA-FROST (production-grade) | Custodial-via-TSS | Possible in principle; no production deployment to a shielded vault | + +## Recommendation for LEZ ↔ ZEC scope + +- **Phase 1 (deliverable):** LEZ ↔ Zcash transparent via the same + pattern used by the ETH-LEZ HTLC reference, with adaptor-signature + variant as a stretch goal for unlinkability. +- **Phase 2 (research, separate work):** LEZ ↔ Zcash shielded using a + Universal-Atomic-Swaps-style construction adapted to RedJubjub / + RedPallas. Treat this as a research deliverable, not a delivery + deliverable. Funding and timeline are open questions; the upstream + cryptographic state of the art does not yet provide a + drop-in design. + +## References + +### Zcash protocol + +- [BIP-199: Hashed Time-Locked Contract transactions](https://github.com/bitcoin/bips/blob/master/bip-0199.mediawiki) +- [ZIP-202: Version 3 Transaction Format for Overwinter](https://zips.z.cash/zip-0202) +- [ZIP-203: Transaction Expiry](https://zips.z.cash/zip-0203) +- [ZIP-224: Orchard Shielded Protocol](https://zips.z.cash/zip-0224) +- [ZIP-304: Sapling Address Signatures](https://zips.z.cash/zip-0304) +- [Zcash Protocol Specification (NU6.1)](https://zips.z.cash/protocol/protocol.pdf) + +### Cryptographic libraries + +- [ZcashFoundation/redjubjub](https://github.com/ZcashFoundation/redjubjub) — RedJubjub (Sapling) +- [ZcashFoundation/reddsa](https://github.com/ZcashFoundation/reddsa) — generic RedDSA (Sapling + Orchard) +- [ZcashFoundation/frost-tools](https://github.com/ZcashFoundation/frost-tools) — FROST threshold signing for Zcash, including rerandomized variant +- [zcash/orchard](https://github.com/zcash/orchard) — Orchard reference implementation + +### Atomic swap research and prior art + +- [Universal Atomic Swaps (Thyagarajan, Malavolta, Moreno-Sánchez, 2022)](https://eprint.iacr.org/2021/1612) — generic scriptless atomic swap framework +- [Multi-Party, Multi-Blockchain Atomic Swap Protocol with Universal Adaptor Secret (2024)](https://arxiv.org/pdf/2406.16822) +- [Zswap: zk-SNARK Based Non-Interactive Multi-Asset Swaps](https://eprint.iacr.org/2022/1002.pdf) +- [Zwap forum thread](https://forum.zcashcommunity.com/t/zwap-unlinkable-cross-chain-atomic-swaps/55104) — Zcash transparent + Ethereum, ECDH-based +- [Maya Protocol Zcash docs](https://docs.mayaprotocol.com/mayachain-dev-docs/protocol-development/chain-clients/zcash) — vault/TSS model (for contrast) +- [comit-network/xmr-btc-swap](https://github.com/comit-network/xmr-btc-swap) — closest production analogue for adaptor swaps to a non-scriptable chain