Giuseppe

Solana order book, zero-copy market primitives in MagicBlock ephemeral rollup.

Giuseppe is an exchange-oriented Solana program written in low-level Rust with Pinocchio. It is building toward a CLOB architecture where custody and durable state live on Solana L1, while the order book can be delegated to MagicBlock ephemeral rollups for lower-latency execution.

🚨 This repository is not a finished end-user DEX yet. It is the exchange kernel: the part that matters most for correctness, latency, and long-term architecture.

Table of Contents

• Why Giuseppe
• What Exists Today
• Architecture
• Repository Layout
• Current Instruction Surface
• Software Architecture Gains
• Testing
• Known Gaps
• Getting Started
• Roadmap
• References

Why Giuseppe

Most on-chain exchange projects talk about performance after they already committed to a slow or hard-to-evolve contract shape. Giuseppe starts at the opposite end.

It is designed around:

• a reusable matching engine instead of instruction-coupled business logic,
• zero-copy fixed-layout state instead of heavy serialization,
• explicit locked/free balance accounting,
• and a first-class L1-to-ephemeral-rollup lifecycle instead of bolted-on scaling later.

What Exists Today

The current repository implements a meaningful slice of the exchange stack.

Implemented

• Program entrypoint and instruction dispatch
• Market initialization path
• IOC taker Swap flow
• FIFO price-time-priority matching engine
• Zero-copy market header and in-account order book state
• Trader balance accounting for locked/free lots
• MagicBlock delegation, commit, and undelegation instruction hooks
• Unit tests for matching behavior
• LiteSVM integration tests for end-to-end swap execution

In Progress

• Production-grade market initialization
• Full maker lifecycle
• Deposit and withdrawal flows
• Limit-order placement and cancellation instructions
• Internal persistent balance ledger
• Finalized delegated-market PDA and authority model

So the right way to read this repo is:

implemented exchange core, incomplete product surface

Architecture

Giuseppe is structured around a clean split between matching, settlement, and delegated execution.

High-Level Model

                +----------------------------------+
                |        Solana L1 (durable)       |
                |----------------------------------|
                | market config                    |
                | vault custody                    |
                | fee accounting                   |
                | final committed state            |
                +----------------+-----------------+
                                 |
                                 | delegate / commit / undelegate
                                 |
                +----------------v-----------------+
                |  MagicBlock Ephemeral Rollup     |
                |----------------------------------|
                | low-latency market execution     |
                | mutable order book state         |
                | fast matching path               |
                +----------------------------------+

Current Code-Level Split

1. Matching Engine

src/engine/matching.rs

This module contains the exchange core:

• walks the opposite side of the book,
• enforces price crossing,
• applies FIFO priority,
• computes fill amounts,
• updates maker state,
• returns aggregate matching results.

It does not own account parsing or token transfer logic. That separation is one of the strongest parts of the repository.

2. Settlement and Instruction Orchestration

src/instructions/swap.rs

The Swap instruction is intentionally thin:

• validate accounts and market header,
• load zero-copy state,
• call the matcher,
• apply fill thresholds,
• compute taker fees,
• settle SPL token transfers,
• update fee counters and sequence state.

Matching is business logic. Settlement is chain interaction. Giuseppe separates those layers correctly.

3. Persistent Market Metadata

src/state/market_header.rs

This file defines durable market metadata:

• market status,
• size configuration,
• base/quote token parameters,
• fee recipient,
• sequence number,
• lot and tick configuration.

4. Book and Trader State

src/state/fifo.rs
src/state/trader_state.rs

The order book uses FIFO semantics over typed order IDs and resting orders, with trader state tracking:

• locked quote lots,
• free quote lots,
• locked base lots,
• free base lots.

That balance model is essential for any serious exchange implementation.

5. Delegation Lifecycle

src/instructions/delegate_book.rs
src/instructions/commit_book.rs
src/instructions/undelegate_book.rs

These instructions already model the intended runtime lifecycle:

• delegate market state to MagicBlock,
• commit delegated state back to L1,
• undelegate and return ownership,
• handle the callback path.

Repository Layout

.
├── src/
│   ├── engine/         # matching engine and engine tests
│   ├── instructions/   # initialize, swap, delegate/commit/undelegate
│   ├── macros/         # typed wrappers and enum helpers
│   ├── state/          # market header, order book, trader state, enums
│   ├── tests/          # LiteSVM integration tests
│   └── lib.rs          # program entrypoint
├── research/
│   └── EXCHANGE_DESIGN_V1.md
├── tests/
│   └── devnet_initialize.rs
├── Cargo.toml
└── README.md

Current Instruction Surface

From src/instructions/mod.rs:

Instruction	Purpose
Initialize	Set up market state and vault structure
Swap	IOC taker flow over the current book
DelegateBook	Move market account into delegated execution
CommitBook	Sync delegated market state back to L1
UndelegateBook	Return delegated market to L1 ownership
UndelegationCallback	Finalize undelegation callback flow

Software Architecture Gains

This is where the repository is strongest.

Zero-Copy Exchange State

The state layer uses #[repr(C)], Pod, fixed-size wrappers, and direct byte casting. That gives:

• predictable layout,
• lower overhead,
• easier account sizing,
• and a more realistic base for performance-sensitive trading logic.

Clear Balance Semantics

The locked/free split in TraderState gives the codebase a clean foundation for:

• reservations,
• execution,
• settlement,
• cancellations,
• and eventual withdrawal flows.

Runtime Portability

By separating matching from token movement, Giuseppe can evolve toward:

• L1 execution,
• delegated execution,
• and simulation environments

without rewriting the exchange rules each time.

Early ER-Native Design

Most projects write a monolithic contract first and only later discover that rollup delegation changes everything. Giuseppe already includes delegation lifecycle instructions, which is a major architectural advantage.

Testing

The repository has real verification coverage, not just notes and stubs.

Unit Coverage

src/engine/tests.rs covers:

• full fills,
• partial fills,
• multi-level sweeps,
• non-crossing orders,
• empty book behavior,
• match limits,
• quote-budget caps,
• taker fee math.

Integration Coverage

src/tests/swap_integration.rs validates:

• market account construction,
• seeded resting liquidity,
• vault token account setup,
• IOC swap execution through LiteSVM,
• actual token balance changes after settlement.

src/tests/initialize_market.rs also captures the fact that initialization is still incomplete while ensuring the path is at least structurally exercised.

Prerequisites

• Rust
• Cargo
• Solana-compatible toolchain for building/testing dependencies

Run Tests

cargo test

Key Files to Read First

• src/lib.rs
• src/instructions/swap.rs
• src/engine/matching.rs
• src/state/market_header.rs
• src/state/fifo.rs
• research/EXCHANGE_DESIGN_V1.md

Roadmap

The next high-value milestones are straightforward:

1. Finish and harden market initialization.
2. Add deposits, withdrawals, and maker seat lifecycle.
3. Implement limit-order placement and cancellation.
4. Replace manually seeded liquidity in integration tests with natural instruction flows.
5. Harden delegated market PDA derivation and authority checks.
6. Add richer event and receipt structures for fills and settlement.