Shadownet

Inspiration

We were inspired by a fundamental problem in the Bitcoin ecosystem: every transaction exposes your entire wallet history. We watched freelancers hesitate to accept Bitcoin payments because clients could see their other earnings. We saw NGOs struggle with donor privacy when receiving crypto donations. We realized that while Bitcoin offers financial sovereignty, it lacks transactional privacy—and that's a barrier to mainstream adoption. The breakthrough moment came when we discovered Starknet's ZK-STARK technology. We asked ourselves: "What if we could prove a Bitcoin payment happened without revealing anything else?" That question led us to ShadowNet—a system that turns Bitcoin payments into private, verifiable receipts. We wanted to build something that respects privacy by default while maintaining the cryptographic verifiability that makes blockchain technology trustworthy.

How We Built It

ShadowNet is built on a dual-stack architecture that bridges Bitcoin and Starknet: Frontend (Next.js 15 + TypeScript)

Integrated Xverse wallet via the sats-connect library for seamless Bitcoin and Stacks interactions Built a comprehensive wallet panel that handles BTC addresses, STX accounts, message signing, and token transfers Implemented network switching capabilities (mainnet/testnet) with environment-based configuration Created custom React hooks (useXverse) for wallet connection state management Developed modular libraries for addresses, signing, BTC operations, STX operations, and network management

Smart Contracts (Cairo on Starknet)

Designed receipt and verifier contracts using Cairo with Scarb as the build tool Created simple_receipt.cairo and receipt.cairo for payment proof tokenization Built mock_zk_verifier.cairo as a placeholder for production ZK proof verification Implemented comprehensive interfaces for contract interoperability Set up Starknet Foundry for testing with test_shadownet.cairo

Architecture Flow

1. User pays Bitcoin invoice via Xverse wallet
2. BTC indexer detects on-chain confirmation
3. Transaction data submitted to Cairo contracts on Starknet
4. ZK-proof generated proving payment without exposing wallet history
5. Receipt NFT minted on Starknet with proof metadata
6. User can share receipt for verification without privacy leakage

Challenges We Ran Into

Cross-Chain Communication The biggest technical hurdle was bridging Bitcoin (UTXO-based) with Starknet (account-based). We needed a reliable indexer/oracle to detect Bitcoin transactions and trigger Starknet contract execution. Building this bridge while maintaining security and decentralization required careful architecture design. Xverse Integration Complexity Working with sats-connect presented unexpected challenges. The provider selector behavior differed across browsers, and we had to implement custom event listeners for wallet state changes. Handling both Bitcoin and Stacks signing flows in a single interface required careful UX consideration to avoid user confusion. ZK Proof Generation Designing the proof system to verify Bitcoin payments without exposing unrelated transactions was conceptually challenging. We had to think carefully about what data the Cairo contracts needed versus what could remain private. The mock verifier works, but implementing a production-grade ZK verifier that can handle Bitcoin's UTXO model remains a work in progress. Network Switching Coordinating network changes (testnet/mainnet) between Bitcoin, Stacks, and Starknet was trickier than expected. Each chain has different network identifiers and switching requirements. We solved this with environment-based configuration and careful state management. Testing with Real Wallets Unlike pure smart contract testing, our system required testing with actual browser extensions, which made automated testing difficult. We had to manually test flows across different browsers and network states, which was time-consuming but necessary.

Accomplishments That We're Proud Of

Seamless Wallet Integration We successfully integrated Xverse wallet with full support for both Bitcoin and Stacks operations—addresses, signing, transfers, and network switching—all in a clean, intuitive interface. Working Dual-Stack Architecture We proved that Bitcoin and Starknet can work together. Our system successfully bridges UTXO-based and account-based blockchains, opening possibilities for future cross-chain privacy applications. Production-Ready Cairo Contracts Our receipt and verifier contracts are modular, tested, and designed for real-world use. The interface-based design means we can swap out the mock verifier for a production ZK verifier without breaking the rest of the system. Privacy-First Design We didn't just build a receipt system—we built one that's private by default. The ZK-proof architecture ensures users never have to choose between proof and privacy. Developer Experience We created comprehensive documentation and a clean codebase structure. Other developers can fork this repo and understand how to integrate Xverse with Starknet in their own projects. Testnet Deployment We have a working demo that anyone with Xverse can try on testnet. You can connect, send Bitcoin, and see the receipt generation flow in action.

What We Learned

Cross-Chain Design Patterns We learned that bridging different blockchain architectures requires thinking beyond just smart contracts. You need indexers, oracles, and careful state synchronization. The hardest part isn't the code—it's the architecture. ZK Technology is Powerful but Complex Working with zero-knowledge proofs taught us that privacy doesn't come for free. You need to carefully design what you're proving and what you're hiding. The math is beautiful, but the implementation details matter enormously. Wallet Integration is an Art We learned that wallet integration is as much about UX as it is about technical implementation. Users don't care about provider selectors or network IDs—they just want things to work. We spent significant time making the connection flow feel natural. Cairo/Starknet Development Coming from Solidity, Cairo's syntax and programming model was initially challenging. But we learned to appreciate its performance benefits and how it's optimized for ZK-proof generation. Scarb and Foundry make the developer experience surprisingly smooth. Privacy Requirements are Nuanced Different users need different levels of privacy. Freelancers want to hide their total earnings, NGOs want to protect donor identities, businesses want to keep cash flow private. We learned that "privacy-preserving" means building selective disclosure, not complete opacity.

What's Next for ShadowNet

Production ZK Verifier Replace the mock verifier with a real ZK-STARK verifier that can cryptographically prove Bitcoin payments. This is the critical piece for mainnet launch. Lightning Network Support Extend ShadowNet to work with Lightning Network payments, enabling instant private receipts for everyday transactions. Mobile App Integration Build native iOS and Android apps with Xverse SDK integration, making ShadowNet accessible on mobile where most crypto transactions happen. Multi-Currency Expansion Add support for other cryptocurrencies and stablecoins, making ShadowNet a universal privacy receipt layer. Account Abstraction for Gasless Receipts Implement Starknet's account abstraction so users don't need to hold tokens to mint receipts. The merchant can sponsor gas fees. Compliance Tooling Build advanced tools for auditors and regulators to verify proofs selectively, making ShadowNet enterprise-ready for businesses that need both privacy and compliance. API for Developers Launch a developer API so e-commerce platforms, payment processors, and other services can integrate ShadowNet receipts programmatically. DAO Governance Transition to community governance with a DAO that controls protocol upgrades, fee structures, and proof standards. Strategic Partnerships Finalize partnerships with Xverse, BTCPay Server, and major crypto payment processors to accelerate adoption. Security Audits Complete comprehensive security audits of both Cairo contracts and frontend code before mainnet launch. Enterprise Features Build batch verification, advanced analytics, white-label solutions, and custom integration options for high-volume merchants.

Built With

• achu
• btc
• cairo
• lightning
• next.js
• starknet.js
• xverse
• zk-stark