Contra: Enterprise Infrastructure for Internet Capital Markets

Contra is a private execution environment running the Solana Virtual Machine (SVM) off-chain. Built with Solana's SVM (Solana Virtual Machine), Contra provides a complete infrastructure solution to execute thousands of transactions instantly with complete privacy, implement custom compliance rules, and access Solana Mainnet's liquidity.

⚠️ SECURITY NOTICE

This code has not been audited and is under active development. Use at your own risk.

Not recommended for production use with real funds without a thorough security review. The authors and contributors are not responsible for any loss of funds or damages resulting from the use of this library.

---

Documentation

• Architecture Overview - Deep dive into Contra's technical architecture, components, and design decisions
• Technical Requirements - Hardware, software, and network requirements
• Contributing Guide - Guidelines for contributing to Contra

How Contra Works

Contra allows liquidity to move between Solana Mainnet and your private Solana Virtual Machine environment:

• Contra Virtual Machine (CVM): Your private Solana environment. Execute transactions with instant finality, zero fees, and complete control over who participates and what rules apply.
• Contra Escrow Program: Securely bridge assets from Solana mainnet. Users deposit SPL tokens permissionlessly (you configure which tokens are allowed); the program locks funds on Mainnet so they can safely be initialized on your CVM. The program handles withdrawals from your CVM by cryptographically verifying each transaction.
• Contra Withdrawal Program: Enables users to remove liquidity from your CVM back to Mainnet. Uses token-burning to remove tokens from the CVM supply.
• Contra Indexer/Operator: Monitors deposits and withdrawals, orchestrates state synchronization between layers, and maintains an auditable record of all cross-chain activity.

User Transaction Flow

1. Deposit (Mainnet → CVM): Users lock SPL tokens on Solana Mainnet into the escrow program permissionlessly (subject to mint being whitelisted)
2. Transact (CVM): Fast, gasless transfers in your private SVM environment with instant finality
3. Withdraw (CVM → Mainnet): Operators release funds with cryptographic SMT proofs after tokens are burned from the CVM supply

Contra Virtual Machine

On the CVM, transactions are processed through a five-stage pipeline for near-instant finality:

1. Dedup: Filters duplicate transactions using a blockhash-keyed signature cache
2. SigVerify: Parallelizes Ed25519 signature verification across configurable workers
3. Sequencer: Builds a DAG of account dependencies to produce conflict-free batches
4. Executor: Runs batches through the SVM with custom execution callbacks:
   • AdminVM: Bypasses bytecode execution for privileged mint operations
   • GaslessCallback: Synthesizes fee payer accounts on-demand (zero operational overhead)
5. Settler: Batches results every 100ms and commits to PostgreSQL/Redis with atomic writes

Contra Escrow/Withdrawal Programs

• Contra Escrow Program: Mainnet token custody with SMT security
• Contra Withdrawal Program: CVM withdrawal processing (token burning)

Indexer

The indexer monitors Solana Mainnet and your CVM for deposits and withdrawals. It supports two datasource strategies:

1. RPC Polling: Fetches blocks sequentially via getBlock RPC calls
2. Yellowstone gRPC: Real-time block streaming via gRPC (Yellowstone protocol)

Both strategies parse Escrow/Withdraw Program instructions and write to PostgreSQL. The indexer automatically backfills missing slots on restart using parallel RPC batch fetching. An Operator service monitors new transactions in the database to trigger new mints on the CVM or withdrawals back to Mainnet, ensuring synchronization between the two.

Quick Start

Get Contra running locally in under 5 minutes:

# Clone repository
git clone https://github.com/solana-foundation/contra.git
cd contra

# Install dependencies
make install

# Build all components
make build

# Test all components
make all-test

For a quick start on Devnet, see DEVNET_QUICKSTART.md.

Local Development

Prerequisites

• Rust: 1.75+ (stable)
• Solana CLI: 2.2.19 (for programs), 2.3.9 (for using Yellowstone)
• Docker: 26.0+ with Docker Compose
• pnpm: 10.0+ (for TypeScript clients)

See TECHNICAL_REQUIREMENTS.md for complete requirements.

Repository Structure

Component	Path	Description
Contra Virtual Machine	core/	Private SVM runtime with transaction pipeline
Contra DB	core/src/accounts/	Accounts database with multi-backend support
Gateway	gateway/	Read/write node routing service
Escrow Bridge: Deposit Program	contra-escrow-program/	Mainnet token deposit via escrow
Escrow Bridge: Withdrawal Program	contra-withdraw-program/	CVM token withdrawal via burning
Escrow Bridge: Indexer + Operator	indexer/	Mainnet & CVM transaction monitoring & transaction automation
Integration Tests	integration/	Cross-workspace integration tests
Deployment	docker-compose.yml	Full stack deployment configuration

Install Dependencies

make install

Build All Programs

make build

Run Tests

# Run all tests (unit + integration)
make all-test

# Run unit tests only
make unit-test

# Run integration tests only
make integration-test

Contributing

We welcome contributions! Please read our Contributing Guide for guidelines and instructions for contributing to the project.

License

This project is licensed under the MIT License. See LICENSE for details.

Acknowledgments

Built with:

• Agave - Solana Validator Client
• Yellowstone gRPC - Real-time Geyser streaming
• Pinocchio - Efficient Solana program SDK