zdlc: Discreet Log Contracts on Zcash

zdlc is oracle-settled contracts on Zcash, entered and exited through Ironwood. Two parties lock ZEC in a transparent 2-of-2 for the life of one contract, pre-sign one payout per outcome and a refund, and normally close straight back to Ironwood. Every transaction is v6, built through pczt.

Start here

• Try the private market demos, live on Zcash testnet: escrow room (settle a deal), hedge desk (trade a price), auction (discover a price). How they are built and run: demos/.
• Build an app: docs/first-app.md picks a way in (Rust kit, REST with @zdlc/client, Node or browser SDK) and a template, and walks through an escrow in about 100 lines (examples/first_app.rs).
• Install: the packages and binaries are on the releases page: npm install https://github.com/mayohalo/zdlc/releases/download/v0.1.1/zdlc-client-0.1.1.tgz, or zdlc-kit = { git = "https://github.com/mayohalo/zdlc", tag = "v0.1.1" } in Cargo.toml. See docs/first-app.md.
• Run everything locally: just dev (regtest, the desk, two oracles, two nodes), then just room for the three demos at http://127.0.0.1:8080/escrow, /hedge and /auction.

Docs

File	What it covers
docs/design.md	The contract, what Zcash changes, privacy model, architecture tiers
docs/core.md	rust-dlc reuse map, TEE oracle network, Ironwood payout spike
docs/applications.md	Shielded payments, private markets, cross-chain, Zcash-native extensions
docs/plan.md	Phased plan with gates, open questions, sources
docs/beneficiaries.md	Multi-beneficiary payouts: splits, per-outcome overrides, multi-output CETs and closes
site/index.html	The landing page: open it in a browser
docs/kit.md	Developer kit: the Zdlc object, templates, zdlc-node REST API, zdlc-cli, @zdlc/client
docs/first-app.md	Build your first zDLC app: ways in, templates, the flow in Rust and TypeScript, from demo to real app
demos/	The three private market demos: one README each, the code layout, running them
docs/room.md	Hosting the demos: the escrow room and auction in detail, the kit calls behind them, deploying to a server

Demo

A stable-value ZEC payment on the local regtest node: Alice is owed $100 and holds 2 ZEC at $50.00, Bob hedges with 2 ZEC, and an oracle attests the ZEC/USD price at maturity.

infra/zakura/scripts/up.sh
cargo run -p zdlc --release --bin zdlc-demo -- --price 60.00 --settle close   # cooperative close to Ironwood
cargo run -p zdlc --release --bin zdlc-demo -- --price 40.00 --settle cet     # Bob goes silent, Alice uses the CET
cargo run -p zdlc --release --bin zdlc-demo -- --settle refund                # the oracle never attests

Each run uses fresh keys and coins, so they can follow each other on one chain.

Live networks and oracles

zdlc-live runs the contract on Zcash testnet or mainnet through any Zakura JSON-RPC endpoint, given as --node URL or ZDLC_RPC (never stored in the repo). The network and its upgrade heights come from the node; mainnet needs --mainnet. Collateral is capped at 0.05 TAZ (testnet) and 0.01 ZEC (mainnet) a side.

zdlc-oracled is one oracle of a 2-of-2 pair, built to run in a TEE: it attests ZEC/USD (the median close of one minute across four exchanges) and shielded payments (by viewing key), with its keys and nonce counter in sealed state.

export ZDLC_RPC=<your Zakura RPC URL>
cargo run -p zdlc --release --example wallet -- testnet          # seed at ~/.zdlc/testnet-seed.hex; prints the address to fund
cargo run -p zdlc --release --bin zdlc-oracled -- --listen 127.0.0.1:7801 --state a.sealed --sealing-key a.key --node $ZDLC_RPC
cargo run -p zdlc --release --bin zdlc-oracled -- --listen 127.0.0.1:7802 --state b.sealed --sealing-key b.key --node $ZDLC_RPC
cargo run -p zdlc --release --bin zdlc-live -- status
cargo run -p zdlc --release --bin zdlc-live -- run --settle cet --oracles http://127.0.0.1:7801,http://127.0.0.1:7802
cargo run -p zdlc --release --bin zdlc-live -- run --settle refund    # seed-only refund recovery
cargo run -p zdlc --release --bin zdlc-live -- sweep                 # return transparent payouts to the treasury

The RFQ desk

zdlc-desk is a quote board and a sealed mailbox (put it behind TLS). zdlc-trader runs a maker (hedger) or a taker (recipient), each with its own seed; they meet only through the desk, the oracles and the chain.

cargo run -p zdlc --release --bin zdlc-desk -- --listen 127.0.0.1:7900 --state desk.json --node $ZDLC_RPC
cargo run -p zdlc --release --bin zdlc-trader -- address --seed maker.seed      # fund the printed treasury
cargo run -p zdlc --release --bin zdlc-trader -- maker --seed maker.seed --desk http://127.0.0.1:7900 --oracles $ORACLES --premium-bps 50
cargo run -p zdlc --release --bin zdlc-trader -- taker --seed taker.seed --desk http://127.0.0.1:7900 --oracles $ORACLES --collateral 1000000 --settle close
# private quote by memo invitation: no public RFQ
cargo run -p zdlc --release --bin zdlc-trader -- maker ... --invite <taker inbox hex> --invite-collateral 1000000
cargo run -p zdlc --release --bin zdlc-trader -- taker ... --invitations-from <height>
# the taker's side paid 60 % to itself, 40 % to a partner (Ironwood on the close)
cargo run -p zdlc --release --bin zdlc-trader -- taker ... --split self:6000,<tm address>+<raw Ironwood hex>:4000

Developer kit

Build apps on zDLC without touching the protocol (docs/kit.md):

• Rust: one Zdlc object (crates/zdlc-kit).
• Any language: zdlc-node, a REST node (OpenAPI spec), driven by zdlc-cli.
• TypeScript: @zdlc/client.
• Self-custodial JavaScript: @zdlc/sdk. It runs a full node inside Node.js, and its WebAssembly core runs the stateless protocol in browsers.

Templates: stable payment, escrow, bet.

cargo run -p zdlc-kit --release --bin zdlc-node -- --seed alice.seed --node $ZDLC_RPC --desk http://127.0.0.1:7900 --oracles $ORACLES
cargo run -p zdlc-kit --release --bin zdlc-cli -- --token-file alice.seed.token offer escrow --to <identity> --amount 1.5 --question "Delivered?"

Funding by QR

A user funds a contract from any Zcash wallet by scanning a ZIP 321 link (see docs/funding.md):

• Path A: pay a deposit receiver in your own zDLC wallet, which funds the contract from that shielded note after every payout is signed.
• Path B: pay the contract's leg address. The legs are swept into the 2-of-2 once every payout is signed, and each payer can reclaim its own leg from the refund height.

# the taker funds its side from a shielded deposit: it prints a link and QR, any wallet pays it
cargo run -p zdlc --release --bin zdlc-trader -- taker ... --fund deposit
cargo run -p zdlc --release --bin zdlc-trader -- balance --seed taker.seed
cargo run -p zdlc --release --bin zdlc-trader -- shield --seed taker.seed            # CET payouts into the shielded balance
cargo run -p zdlc --release --bin zdlc-trader -- withdraw --seed taker.seed --to <unified address>

A contract can pay up to 16 beneficiaries who never sign: each side's payout splits by basis points, and enumerated outcomes can carry fixed output lists (see docs/beneficiaries.md).

Build and test

Rust 1.97.1 (pinned in rust-toolchain.toml), Docker for the regtest node.

cargo test -p zdlc --release                                         # unit + offline contract tests
infra/zakura/scripts/down.sh; infra/zakura/scripts/up.sh             # fresh Zakura regtest, NU7 at 200
cargo test -p zdlc --release --test regtest -- --ignored --nocapture # Phase 0 gate (needs a fresh chain)
cargo test -p zdlc --release --test phase1 -- --ignored --nocapture  # Phase 1 gate
cargo test -p zdlc --release --test phase2 -- --ignored --nocapture  # Phase 2 gate (needs a fresh chain)
cargo test -p zdlc --release --test phase3 -- --ignored --nocapture  # two oracle daemons, 2-of-2 (needs internet)
cargo test -p zdlc --release --test phase4 -- --ignored --nocapture  # maker and taker processes trade through the desk
cargo test -p zdlc --release --test products -- --ignored --nocapture --test-threads=1  # invitation, escrow, payroll roll
cargo test -p zdlc --release --test beneficiaries -- --ignored --nocapture  # team escrow: 3 payees by CET and by close
cargo test -p zdlc --release --test funding -- --ignored --nocapture --test-threads=1  # funding by QR: deposits, legs, desk trade
cargo test -p zdlc-kit --release --test kit -- --ignored --nocapture --test-threads=1   # zdlc-cli, @zdlc/client, @zdlc/sdk, templates, agents
scripts/build-node.sh && scripts/build-wasm.sh && (cd sdk/sdk && npm install && npm test)  # @zdlc/sdk: native addon and WebAssembly core
cargo run -p zdlc --release --bin zdlc-oracle -- announce zecusd-1    # dev oracle
cargo run -p zdlc --release --bin zdlc-watch -- kit.json              # refund watcher

Results: Phase 0, Phase 1, Phase 2, testnet, Phase 3, Phase 4, beneficiaries, funding by QR, developer kit.