Technical Deep Dive
Architecture
Technical overview of RAIL20's components, ZK circuit, and data flow.
System Overview
- RAIL20Vault — core contract. Holds shielded B20, manages Poseidon Merkle tree, verifies ZK proofs, tracks spent nullifiers.
- Verifier — PLONK verifier (snarkjs auto-generated). Validates proofs on-chain.
- FeeRouter — distributes fees: 50% treasury, 30% broadcasters, 20% buyback-and-burn.
- UsernameRegistry — maps .rail20 names to shielded addresses.
- Broadcaster (off-chain) — self-hosted relayer. Earns gas markup.
Data Flow
text
User (browser)
|
+-- 1. Generate ZK proof locally
v
Broadcaster (relayer)
|
+-- 2. Validate proof + nullifier status
+-- 3. Submit tx (broadcaster pays ETH gas)
v
RAIL20Vault (on-chain)
|
+-- 4. Verify PLONK proof
+-- 5. Check nullifier not spent
+-- 6. Mark nullifier spent
+-- 7. Insert new commitments
+-- 8. Transfer B20 tokens
v
FeeRouter
+-- 9. Split: 50% treasury, 30% broadcaster, 20% burnZK Circuit Design
Single unified circuit compiled with circom 2.x, verified via PLONK (universal setup).
| Parameter | Value |
|---|---|
| Proof system | PLONK (universal setup) |
| Trusted setup | Hermez PTAU 2^14 (54 contributors) |
| Constraints | 5,073 non-linear + 5,409 linear |
| Public inputs | 6 (root, nullifierHash, commitments, txHash, mode) |
| Private inputs | 39 |
| Merkle depth | 16 (65,536 max commitments) |
| Hash function | Poseidon |
| Curve | BN254 |
| Proof size | ~450 bytes (24 uint256) |
| Verify gas | ~250,000 |
Why PLONK over Groth16?
PLONK uses a universal trusted setup. No Phase 2 ceremony, no new toxic waste when circuit changes. Tradeoff: ~450 byte proof (vs 96) and ~20K more gas — negligible on Base L2.
Merkle Tree
16-level Poseidon tree. Append-only — spent notes tracked via nullifier mapping.
javascript
commitment = Poseidon(nullifier, secret, amount)
nullifierHash = Poseidon(nullifier)
pathElements[16] // sibling hashes
pathIndices[16] // 0=left, 1=rightSecurity Model
- PLONK soundness — BN254 curve, no forged proofs without private inputs.
- Poseidon collision resistance — no known collisions.
- Append-only nullifier set — prevents double-spend without revealing which note.
Was this page helpful?