ZShield

Private orderflow and MEV-resistant execution for Solana.

Status

zshield is currently a prototype repo, not a production-ready protocol.

What exists today:

• a scaffolded Anchor commitment program
• a working relay HTTP service with signed-intent admission
• Jito/native-TPU/public-RPC/direct validator-RPC/private-lane execution adapters with receipt tracking and bundle metadata
• durable relay receipt snapshots with restart recovery
• relay edge rate limiting, /metrics JSON counters, and /metrics/prometheus export for operator visibility
• local Prometheus, Alertmanager, and Grafana bring-up assets for relay monitoring and alert routing
• a TypeScript SDK for signed intents and executable Jupiter swap envelopes
• a wallet-enabled demo frontend
• GitHub Actions CI for relay tests, SDK tests, integration tests, and workspace builds
• initial Circom circuit experiments

What does not exist yet:

• real on-chain Groth16 verification
• production-grade key management and operator hardening
• audits and production-grade observability sinks
• multi-region relay coordination

That matters because the original README and architecture docs overstated the current implementation. The repo now documents a launchable path that is honest about what v1 can protect and what it cannot.

Positioning

The credible v1 claim is:

ZShield protects pre-trade orderflow from public-RPC observers and common Solana MEV searchers.

The v1 claim is not:

• full transaction privacy on Solana
• post-trade privacy after execution lands on-chain
• immunity against malicious relays or colluding leaders
• a production Zcash compliance layer

If you market ZShield as "full privacy for Solana", the product and the protocol will not support the claim. If you market it as "private orderflow for Solana", the roadmap is defensible.

Recommended Launch Shape

Launch in three steps:

1. Managed private orderflow beta
2. Production private relay network with partner lanes
3. Optional ZK commitment registry and deeper Zcash-attested extensions

That sequence gets something useful into market faster, while keeping the stronger protocol direction alive.

Docs

• docs/PROTOCOL_REVIEW.md: gap analysis versus the Hermes Zcash plans and the current repo
• docs/ARCHITECTURE.md: recommended production architecture and trust model
• docs/PRODUCTION_READINESS.md: launch gates, blockers, milestones, and operational checklist
• docs/GO_TO_MARKET.md: positioning, messaging, partnerships, and launch plan
• docs/OBSERVABILITY.md: Prometheus metrics, alert thresholds, and dashboard guidance
• docs/RUNBOOKS.md: relay operations and incident response playbooks
• ops/monitoring/: local Prometheus and Grafana stack for relay metrics and alert bring-up
• ops/monitoring/alertmanager/: local Alertmanager routing config for relay alerts
• ops/deploy/: self-hostable Docker Compose stack for relay, frontend, and monitoring
• ops/drills/: executable operator drills for fallback and backlog checks

Repo Layout

• circuits/: Circom experiments for commitment and order validity proofs
• programs/zshield/: Anchor commitment registry prototype
• relay/: relay prototype for private submission
• sdk/: SDK scaffold for private swap flow
• frontend/: demo UI
• tests/: placeholder tests

Frontend Demo

The frontend now calls the real @zshield/sdk private-swap path from a browser wallet instead of returning a mock result. It also surfaces relay health, receipt persistence state, recent receipts, relay edge metrics, and Jito bundle metadata for showcase and operator-demo flows.

Configure it with:

• frontend/.env.example
• NEXT_PUBLIC_ZSHIELD_RELAY_URL
• NEXT_PUBLIC_ZSHIELD_RPC_URL
• NEXT_PUBLIC_ZSHIELD_PROGRAM_ID

The demo also exposes a dedicated relay status surface at /status.

Do not put a relay shared secret in a public frontend. Managed encryption secrets belong on trusted clients or relay-side infrastructure, not in browser code.

JavaScript Tooling

This repo now uses bun for JavaScript workspace management.

Key commands:

• bun install
• bun run build
• bun run test
• bun run test:integration
• bun run ops:monitoring:up
• bun run ops:monitoring:down
• bun run ops:monitoring:logs
• bun run ops:deploy:render-alertmanager
• bun run ops:deploy:config
• bun run ops:deploy:bootstrap:staging
• bun run ops:deploy:bootstrap:production
• bun run ops:deploy:validate:staging
• bun run ops:deploy:validate:production
• bun run ops:deploy:config:staging
• bun run ops:deploy:config:production
• bun run ops:drill:jito
• bun run ops:drill:tpu
• bun run ops:drill:backlog
• cargo test --manifest-path relay/Cargo.toml

Relay execution envs:

• ZSHIELD_RELAY_JITO_URL
• ZSHIELD_RELAY_TPU_WEBSOCKET_URL
• ZSHIELD_RELAY_VALIDATOR_RPC_URLS
• ZSHIELD_RELAY_VALIDATOR_RPC_AUTH_TOKEN
• ZSHIELD_RELAY_PRIVATE_LANE_URL
• ZSHIELD_RELAY_PRIVATE_LANE_AUTH_TOKEN
• ZSHIELD_RELAY_SUBMISSION_RETRY_AFTER_MS
• ZSHIELD_RELAY_SUBMISSION_MAX_ATTEMPTS

Testing

SDK checks:

• cd sdk && bun run test -- --runInBand
• cd sdk && bun run test:integration

The integration script boots the Rust relay, mocks Solana RPC plus Jupiter/Jito dependencies, submits a real SDK private swap, and verifies receipt finalization.

Near-Term Priority

If the goal is to launch and market soon, do not spend the next sprint polishing the current placeholders. Replace overclaiming with a narrow wedge:

• Jupiter first
• Jito and validator partners second
• measurable MEV savings and fill-rate proof
• invite-only alpha before broad launch

That is the shortest path from repo to product.