Skip to content

RFP-003: add Zcash transparent pair, scope out shielded #49

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
fryorcraken wants to merge 1 commit into
base: master
Choose a base branch
from
Open

RFP-003: add Zcash transparent pair, scope out shielded #49

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 54 additions & 22 deletions RFPs/RFP-003-atomic-swaps.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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** —
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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


Expand Down Expand Up @@ -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

Expand Down
Loading