Skip to content

Milestone 2: Real blockchain transactions with ZingoLib#3

Closed
Timi16 wants to merge 48 commits intozecdev:mainfrom
Timi16:main
Closed

Milestone 2: Real blockchain transactions with ZingoLib#3
Timi16 wants to merge 48 commits intozecdev:mainfrom
Timi16:main

Conversation

@Timi16
Copy link

@Timi16 Timi16 commented Nov 24, 2025

Description:
Hey team! 👋
Wrapped up M2 and wanted to get this merged. TL;DR: we've got real blockchain transactions working through ZingoLib, but hit a few bumps along the way that I've documented.
What's New
Built out the full stack for real Zcash transactions on regtest:

CLI tool (zecdev) - One command to spin everything up. Takes about 10-15 min because we need to mine 101 blocks for coinbase maturity, but it's all automated now.
Real transactions - Ditched the mock transaction IDs. Everything goes through ZingoLib/Zingo wallet now with actual on-chain TXIDs.
Faucet rewrite - Python Flask API that talks to the wallet via docker exec. Not the prettiest solution but it works reliably.
Auto-mining - Custom Zebra build with internal-miner feature. Mines blocks automatically until we hit coinbase maturity.
Tests - 4 out of 5 smoke tests passing. The 5th one is flaky in automation but works fine when you test manually. See known issues below.

Tests Results
[1/5] Zebra RPC connectivity... ✓ PASS
[2/5] Faucet health check... ✓ PASS
[3/5] Faucet stats endpoint... ✓ PASS
[4/5] Faucet address retrieval... ✓ PASS
[5/5] Faucet funding request... ✗ FAIL (timing issue)
The last test fails because the wallet balance shows 0 initially - looks like a race condition between mining rewards hitting the wallet and the test running. Manual testing confirms transactions work fine though.
Known Issues
Wallet sync bug - If you delete volumes and restart, the wallet freaks out about block heights being mismatched. Workaround is to nuke all volumes before restarting. I'm planning to fix this in M3 by making the wallet ephemeral (tmpfs).
Transparent mining only - Hit a wall with Zebra's internal miner. Even though the Zcash protocol has supported shielded coinbase since Heartwood (2020), Zebra's internal miner implementation doesn't support Orchard UAs yet. There's an open issue tracking it (zebra#5929). For now we're mining to a transparent address which works fine for testing.
Test reliability - The funding request test is unreliable in automation but I've verified the actual functionality works. Probably need better sync handling before running tests.
Files Changed
Main additions:

Complete CLI rewrite in Rust (cli/src/)
Python faucet with real wallet integration (faucet/)
Custom Zebra Dockerfile with internal miner (docker/zebra/)
Zingo wallet container (docker/zingo/)
Updated configs for development use
Comprehensive docs in specs/

How to Test
bash# Build and start (grab coffee, takes 10-15 min)
cd cli && cargo build --release && cd ..
./cli/target/release/zecdev up --backend=lwd

Smoke tests

./cli/target/release/zecdev test

Manual transaction test if you want to verify

curl -X POST http://127.0.0.1:8080/request
-H "Content-Type: application/json"
-d '{"address": "u1...", "amount": 10.0}'
Next Steps (M3)

Fix the wallet sync issue properly
Get test 5/5 reliable
Package this as a reusable GitHub Action
Add full E2E flows
Maybe look into Zaino support if time permits

Notes
This took longer than expected - mostly because of the wallet sync issues and figuring out the Zebra internal miner limitations. But we're in a good spot now with real transactions actually working.
The transparent mining thing isn't ideal but it's a known Zebra limitation, not something we did wrong. Figured it's better to ship with that documented than block on upstream.
Let me know if you want me to walk through anything or if something's unclear!

Merge when ready

@Timi16 Timi16 closed this Dec 10, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants