Contra is a payment channel with direct access to Solana Mainnet liquidity. Contra provides a complete infrastructure solution to execute thousands of transactions instantly with privacy, control and permissioning, while assets are readily accessible to and from Solana Mainnet.
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.
- 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
Contra operates as a payment channel with direct access to Solana Mainnet liquidity:
- Contra Channel: Your private transaction batching system with direct Solana Mainnet access. Execute transactions with instant finality and full control over who participates and what rules apply.
- Contra Escrow Program: Makes assets readily accessible to the payment channel. Users deposit SPL tokens. The program locks funds in escrow for use within the channel.
- Contra Withdrawal Program: Withdrawals are initiated by sending tokens to the withdraw program inside the payment channel. The withdraw program burns the tokens and SPL tokens are released from the escrow program.
- Contra Indexer/Operator: Monitors deposits and withdrawals, orchestrates state synchronization, and maintains an auditable record of all activity.
This flow shows how a bank creates a token mint and issues tokenized deposits on Solana mainnet, initializes a Contra payment channel for transactions between bank customers [Alice and Bob].
sequenceDiagram
participant Bank
participant Mainnet as Solana Mainnet
participant Channel as Contra Payment Channel
%% Setup Phase
Note over Bank,Mainnet: SETUP
Bank->>Mainnet: Create Token Mint (SPL/Token-2022)
Mainnet-->>Bank: Mint Authority Created
Bank->>Mainnet: Initialize Escrow for Payment Channel
Mainnet-->>Bank: Escrow Instance Active
Bank->>Channel: Initialize Contra Payment Channel
Channel-->>Bank: Channel Ready
Bank->>Mainnet: Link Payment Channel to Escrow
Note over Bank,Channel: Bank retains full control<br/>as channel operator
%% Issuance Phase
Note over Bank,Mainnet: TOKENIZED DEPOSIT ISSUANCE
Bank->>Bank: Receive $10M USD from customers
Note right of Bank: Traditional banking<br/>deposit collection
Bank->>Mainnet: Mint 10M Tokenized Deposits
Note over Mainnet: Bank mints tokens 1:1<br/>backed by real deposits
Mainnet-->>Bank: 10M TD Tokens Created
%% Channel Funding
Note over Bank,Channel: CHANNEL FUNDING
Bank->>Mainnet: Lock 10M TD in Escrow
Note over Mainnet: Tokens locked for<br/>channel operations
Channel-->>Bank: 10M TD Available in Channel
Note over Channel: Funds automatically<br/>available after lock
Note over Channel: Channel participants can:<br/>• Transfer privately<br/>• View own balance<br/>• Request withdrawals
This flow demonstrates a simple $1,000 transfer between bank customers Alice and Bob within the payment channel, showing how privacy is maintained while the bank retains control.
sequenceDiagram
participant Alice
participant Bob
participant Channel as Contra Payment Channel
participant Bank
%% Initial State
Note over Alice,Bob: INITIAL STATE (Bank Payment Channel)
Note left of Alice: Balance: $50,000 TD
Note right of Bob: Balance: $30,000 TD
%% Transfer
Alice->>Channel: Transfer $1,000 TD to Bob
Channel->>Channel: Validate Transaction
Note over Channel: Check balance,<br/>AML limits
Channel->>Bank: Transaction Notification
Bank->>Bank: Apply Business Rules
Bank-->>Channel: Approved
Channel->>Channel: Execute Transfer
Note over Channel: Atomic Operation:<br/>Alice: -$1,000<br/>Bob: +$1,000
Channel-->>Alice: New Balance: $49,000 TD
Channel-->>Bob: New Balance: $31,000 TD
Channel->>Bank: Update Audit Log
Note over Channel: Transaction complete:<br/>✅ Instant<br/>✅ Private<br/>✅ Compliant
This flow shows how Bob withdraws $1,000 from the payment channel, subject to the bank's compliance policies and approval.
The flow shows two withdrawal methods that allow Bob to withdraw while preserving privacy.
sequenceDiagram
participant Bob
participant Channel as Contra Payment Channel
participant Bank
participant Mainnet as Solana Mainnet
participant BobWallet as Bob's Wallet
%% Initial State
Note over Bob: Channel Balance: $31,000 TD
%% Withdrawal Request
Bob->>Channel: 1. Request $1,000 Withdrawal
Channel->>Bank: 2. Process Withdrawal
Bank->>Bank: 3. Compliance Check
Bank-->>Channel: 4. Approved
%% Privacy Options
Note over Bank,Mainnet: PRIVACY OPTIONS
alt Batched Settlement
Bank->>Bank: 5a. Queue with other withdrawals
Note over Bank: Aggregate:<br/>Bob: $1,000<br/>Alice: $500<br/>Carol: $2,000
Bank->>Mainnet: 5b. Batch Settlement ($3,500)
Mainnet->>Bank: 5c. Tokens Released
Bank->>BobWallet: 5d. Distribute $1,000 TD
Note right of BobWallet: No direct link<br/>to channel account
else Confidential Transfer (Token-2022)
Bank->>Mainnet: 5a. Initiate Confidential Transfer
Note over Mainnet: Amount encrypted<br/>with ZK proof
Mainnet->>BobWallet: 5b. Encrypted $1,000 TD
BobWallet->>BobWallet: 5c. Decrypt with key
Note right of BobWallet: Balance visible only<br/>to Bob and Bank
end
Channel-->>Bob: 6. New Balance: $30,000 TD
Channel->>Bank: 7. Log Withdrawal
Within the payment channel, transactions are processed through a five-stage pipeline for near-instant finality:
- Dedup: Filters duplicate transactions using a blockhash-keyed signature cache
- SigVerify: Parallelizes Ed25519 signature verification across configurable workers
- Sequencer: Builds a DAG of account dependencies to produce conflict-free batches
- Executor: Runs batches with custom execution callbacks:
- AdminVM: Bypasses bytecode execution for privileged mint operations
- GaslessCallback: Synthesizes fee payer accounts on-demand (zero operational overhead)
- Settler: Batches results every 100ms and commits to PostgreSQL/Redis with atomic writes
- Contra Escrow Program: Mainnet token custody with SMT security
- Contra Withdrawal Program: Channel withdrawal processing (token burning)
The indexer monitors Solana Mainnet and your payment channel for deposits and withdrawals. It supports two datasource strategies:
- RPC Polling: Fetches blocks sequentially via
getBlockRPC calls - 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 in the channel or withdrawals back to Mainnet, ensuring synchronization.
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-testFor a quick start on Devnet, see DEVNET_QUICKSTART.md.
- 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.
| Component | Path | Description |
|---|---|---|
| Contra Core | core/ | Payment channel transaction pipeline |
| Contra DB | core/src/accounts/ | Accounts database with multi-backend support |
| Gateway | gateway/ | Read/write node routing service |
| Escrow Program | contra-escrow-program/ | Mainnet token deposit via escrow |
| Withdrawal Program | contra-withdraw-program/ | Channel token withdrawal via burning |
| Indexer + Operator | indexer/ | Mainnet & channel transaction monitoring & automation |
| Integration Tests | integration/ | Cross-workspace integration tests |
| Deployment | docker-compose.yml | Full stack deployment configuration |
make installmake build# Run all tests (unit + integration)
make all-test
# Run unit tests only
make unit-test
# Run integration tests only
make integration-testWe welcome contributions! Please read our Contributing Guide for guidelines and instructions for contributing to the project.
This project is licensed under the MIT License. See LICENSE for details.
Built with:
- Agave - Solana Validator Client
- Yellowstone gRPC - Real-time Geyser streaming
- Pinocchio - Efficient Solana program SDK