Contribution Guidelines

Contribution Guidelines

ZK Circuit Contributors • Relayer Operator Setup

SnarkSide is a modular, cryptographically-intensive protocol. Contributions are welcome across multiple verticals—ranging from ZK circuit optimization to relayer infrastructure and intent matching logic. This section outlines the technical requirements and contribution pathways for developers who wish to participate in SnarkSide’s evolution.

1. General Expectations

Due to the sensitive and adversarial context in which SnarkSide operates (e.g., encrypted leverage, liquidation incentives, MEV-resistance), contributions must meet rigorous correctness and security standards.

All pull requests will undergo:

  • Code review by core maintainers

  • Formal specification comparison (when relevant)

  • Static/dynamic audits (for verifier logic)

  • Gas benchmarking (for on-chain contributions)

  • Proof verifiability testing (for circuit updates)

2. ZK Circuit Contributors

Circuit Stack

SnarkSide currently uses:

  • Circom v2.1+ for proving logic

  • SnarkJS for trusted setup and local testing

  • Groth16 for production verifier integration

  • Poseidon Hash for all in-circuit commitments

  • Planned optionality: Halo2 (for zk-native recursion)

Directory Structure

circuits/
│
├── trade_intent/
│   ├── intent.circom
│   └── constraints/
│       └── poseidon.circom
│
├── match_verification/
│   ├── dual_intent.circom
│   └── timelock.circom
│
├── vault_transition/
│   ├── deposit.circom
│   ├── update.circom
│   └── settle.circom
│
├── liquidation/
│   ├── margin_check.circom
│   └── price_proof.circom

Each module must include:

  • A README.md explaining the constraints and circuit purpose

  • A test_vectors.json with valid/invalid inputs

  • A verifier.sol compiled output (can be left to CI)

Guidelines

  • Every new circuit must include a Poseidon-committed output root

  • No unbounded loops or recursive constraints (unless Halo2)

  • All nonces, salts, and nullifiers must pass replay protection testing

  • Naming conventions must follow snake_case.circom and be documented

Testing

Use the included test harness:

yarn run compile:circuits
yarn run test:circuits

All PRs must pass:

  • Constraint satisfaction tests

  • Gas cost benchmarks

  • Invariant preservation (circuit-specific)

3. Relayer Operator Setup

SnarkSide relayers form the off-chain backbone of the matching engine. Contributions are welcomed for:

  • New relayer implementations (Go, Rust, TypeScript)

  • Circuit-aware matching optimizations

  • MPC handshake integrations

  • FHE gateway simulations (experimental)

Relayer Requirements

Each relayer must implement the following services:

Service
Description

Intent Aggregator

Gathers encrypted user intents

Intent Matcher

Computes valid match pairs

Witness Generator

Computes witness data for proof generation

Proof Submitter

Interacts with Verifier.sol to post batched matches

Vault Cache

Off-chain Merkle root synchronizer (non-authoritative)

Installation (Reference TypeScript)

git clone https://github.com/snarkside/relayer-ts.git
cd relayer-ts
yarn install
cp .env.example .env
yarn start

Required environment variables:

RPC_URL=
PRIVATE_KEY=
VERIFIER_CONTRACT_ADDRESS=
INTENT_RELAY_ENDPOINT=

Relayers must commit to:

  • Block interval batching rate ≤ 2s

  • Accurate intent sorting with timestamp proof

  • Zero leakage of decrypted intent content

  • Public dashboard of uptime and batching proof stats

4. Issue Labeling

Label
Usage

zk-circuit

Circom or Halo2-based constraint updates

relayer

Intent sync, matching, proof posting

oracle

Price feed logic or commit-reveal flow

vault

State transition circuits or Merkle integration

frontend

UI changes for encrypted position display

security

Replay edge cases, nullifier leakage, circuit bugs

gas

Optimizations in verifier or calldata footprint

5. CI & Verifier Auto-Testing

Each PR to main or dev triggers:

  • Circom compilation

  • Groth16 setup with test entropy

  • Proof verification (mock and Solidity verifier)

  • Verifier gas usage measurement

  • Regression test comparison

Failures in any of these stages will block merge until resolved.

6. Contribution Flow

1. Fork the repo
2. Create a new feature branch (e.g. zk/liquidation-circuit-fix)
3. Make changes with tests and documentation
4. Submit a PR referencing the related GitBook or spec
5. Await core maintainer review + auditor ping

7. Contribution Scope Priority

  • ZK circuit upgrades (intent aggregation, nullifier constraints)

  • Verifier calldata compression

  • Relayer performance tuning and MPC integration

  • Encrypted LP analytics (funding skew via FHE, in progress)

  • Research writeups and GitBook expansions

Conclusion

Contributing to SnarkSide is not trivial—it demands cryptographic literacy, rigorous testing, and security-first thinking. But for contributors who understand the cost of trust and the value of anonymity, it is a chance to build what traditional finance never will: a market where no one can see you coming—but every proof can be trusted.

PreviousUpgradeability DesignNextBuild Requirements

Last updated