Skip to content

Commit 69ad415

Browse files
rz1989srz1989s
committed
docs: Add LUMOS vs Codama comparison guide
- Create dedicated comparison page at guides/lumos-vs-codama.md - Add sidebar entry in Guides section with 'New' badge - Add brief Codama section in introduction.md with link to full comparison The guide explains: - Different layers where each tool operates - Workflow direction (schema-first vs IDL-centric) - What each tool generates (data structures vs client SDKs) - When to use each tool (decision matrix) - How to use both together in a combined workflow
1 parent c47445f commit 69ad415

File tree

3 files changed

+334
-0
lines changed

3 files changed

+334
-0
lines changed

‎astro.config.mjs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,7 @@ export default defineConfig({
6161
{
6262
label: 'Guides',
6363
items: [
64+
{ label: 'LUMOS vs Codama', slug: 'guides/lumos-vs-codama', badge: { text: 'New', variant: 'tip' } },
6465
{ label: 'Using npm Package', slug: 'guides/npm-package', badge: { text: 'New', variant: 'success' } },
6566
{ label: 'Schema Versioning', slug: 'guides/versioning', badge: { text: 'New', variant: 'success' } },
6667
{ label: 'Schema Migrations', slug: 'guides/schema-migrations', badge: { text: 'New', variant: 'success' } },

‎src/content/docs/getting-started/introduction.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -183,6 +183,19 @@ IR-based design makes adding new target languages straightforward.
183183
- ✅ Production-ready code
184184
- ⚠️ Learning curve (minimal)
185185

186+
### Codama
187+
188+
**Different tool, different purpose:** Codama generates client SDKs from existing programs.
189+
190+
- ✅ Great for building clients for deployed programs
191+
- ✅ Supports Dart and Umi framework
192+
- ✅ Generates full SDKs with instruction builders
193+
- ⚠️ Works post-deployment, not pre-deployment
194+
195+
LUMOS and Codama are **complementary**, not competing. Use LUMOS to define data structures, Codama to generate client SDKs.
196+
197+
**[See full comparison →](/guides/lumos-vs-codama/)**
198+
186199
---
187200

188201
## Real-World Impact

‎src/content/docs/guides/lumos-vs-codama.md‎

Lines changed: 320 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,320 @@
1+
---
2+
title: LUMOS vs Codama
3+
description: Understanding the differences between LUMOS and Codama for Solana development - complementary tools for different stages of your workflow.
4+
---
5+
6+
## TL;DR
7+
8+
**LUMOS and Codama are complementary, not competing.**
9+
10+
- **LUMOS** = Define data schemas → Generate Rust + TypeScript code (pre-deployment)
11+
- **Codama** = Parse existing programs → Generate client SDKs (post-deployment)
12+
13+
They work at different layers of Solana development and can be used together.
14+
15+
---
16+
17+
## Where Each Tool Fits
18+
19+
```
20+
┌─────────────────────────────────────────────────────────────┐
21+
│ YOUR SOLANA PROGRAM │
22+
│ ┌────────────────────────────────────────────────────────┐ │
23+
│ │ │ │
24+
│ │ ┌──────────────────┐ │ │
25+
│ │ │ Account Data │ ◄── LUMOS generates this │ │
26+
│ │ │ (structs/enums) │ (data structure code) │ │
27+
│ │ └──────────────────┘ │ │
28+
│ │ │ │
29+
│ │ ┌──────────────────┐ │ │
30+
│ │ │ Instructions │ (you write this manually │ │
31+
│ │ │ (program logic) │ or with Anchor) │ │
32+
│ │ └──────────────────┘ │ │
33+
│ │ │ │
34+
│ └────────────────────────────────────────────────────────┘ │
35+
└─────────────────────────────────────────────────────────────┘
36+
▲
37+
│ Codama parses program
38+
│ and generates...
39+
▼
40+
┌─────────────────────────────────────────────────────────────┐
41+
│ CLIENTS │
42+
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
43+
│ │ JS │ │ Rust │ │ Python │ │ Dart │ │
44+
│ │ Client │ │ Client │ │ Client │ │ Client │ │
45+
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │
46+
│ │
47+
│ ◄── Codama generates these (SDK code to interact) │
48+
└─────────────────────────────────────────────────────────────┘
49+
```
50+
51+
**Key insight:** LUMOS generates code that goes *inside* your program. Codama generates code that *interacts with* your program from outside.
52+
53+
---
54+
55+
## What is Codama?
56+
57+
[Codama](https://github.com/codama-idl/codama) is a code generation framework that creates standardized descriptions of Solana programs. It works around a central concept called the **Codama IDL** (Interface Definition Language).
58+
59+
**Core workflow:**
60+
```
61+
Existing Program → Parse → Codama IDL → Generate Clients
62+
or
63+
Anchor IDL → Convert → Codama IDL → Generate Clients
64+
```
65+
66+
**What Codama does:**
67+
- Parses existing Solana programs (via Rust macros) or Anchor IDL files
68+
- Creates a unified IDL representation with 60+ node types
69+
- Generates client SDKs in multiple languages (JS, Rust, Python, Dart)
70+
- Produces documentation and tooling for program interfaces
71+
- Enables blockchain explorers and wallets to understand your program
72+
73+
**Primary use case:** "I have a deployed Solana program, now I need to generate client libraries so others can interact with it."
74+
75+
---
76+
77+
## What is LUMOS?
78+
79+
LUMOS is a **schema-first DSL** (Domain Specific Language) for defining data structures with guaranteed type safety across Rust and TypeScript.
80+
81+
**Core workflow:**
82+
```
83+
.lumos Schema → Parse → IR → Generate Rust + TypeScript
84+
```
85+
86+
**What LUMOS does:**
87+
- Defines data structures in a clean, Rust-like syntax
88+
- Generates Rust structs with proper Borsh serialization
89+
- Generates TypeScript interfaces with matching Borsh schemas
90+
- Ensures type safety between on-chain and off-chain code
91+
- Supports Anchor framework integration via `#[account]` attribute
92+
93+
**Primary use case:** "I want a single source of truth for my data types that generates synchronized Rust and TypeScript code."
94+
95+
---
96+
97+
## Key Differences
98+
99+
### 1. Workflow Direction
100+
101+
| Aspect | LUMOS | Codama |
102+
|--------|-------|--------|
103+
| **Direction** | Forward (schema → code) | Reverse (program → clients) |
104+
| **Input** | `.lumos` schema files | Existing programs or Anchor IDL |
105+
| **Stage** | Pre-deployment | Post-deployment |
106+
107+
**LUMOS:** You write schemas first, then generate the code that becomes part of your program.
108+
109+
```
110+
Write .lumos → Generate → Build Program → Deploy
111+
```
112+
113+
**Codama:** You have a program, then generate clients to interact with it.
114+
115+
```
116+
Build Program → Deploy → Parse with Codama → Generate Clients
117+
```
118+
119+
### 2. What They Generate
120+
121+
**LUMOS generates data structure code:**
122+
123+
```rust
124+
// Input: schema.lumos
125+
#[solana]
126+
#[account]
127+
struct PlayerAccount {
128+
wallet: PublicKey,
129+
level: u16,
130+
experience: u64,
131+
}
132+
```
133+
134+
```rust
135+
// Output: generated.rs (goes INTO your program)
136+
use anchor_lang::prelude::*;
137+
138+
#[account]
139+
pub struct PlayerAccount {
140+
pub wallet: Pubkey,
141+
pub level: u16,
142+
pub experience: u64,
143+
}
144+
```
145+
146+
**Codama generates client SDK code:**
147+
148+
```typescript
149+
// Output: client SDK (CALLS your program from outside)
150+
await program.methods
151+
.createPlayer()
152+
.accounts({
153+
player: playerPda,
154+
authority: wallet.publicKey,
155+
})
156+
.rpc();
157+
```
158+
159+
### 3. Scope & Coverage
160+
161+
| Feature | LUMOS | Codama |
162+
|---------|-------|--------|
163+
| Struct definitions | ✅ | ✅ (via IDL) |
164+
| Enum definitions | ✅ | ✅ (via IDL) |
165+
| Borsh serialization | ✅ | ✅ |
166+
| Instruction builders | ❌ | ✅ |
167+
| Account validation | ❌ | ✅ |
168+
| Error types | ❌ | ✅ |
169+
| Event parsing | ❌ | ✅ |
170+
| CLI generation | ❌ | ✅ |
171+
| Documentation | ❌ | ✅ |
172+
173+
**LUMOS** is focused: data schemas with Borsh serialization.
174+
175+
**Codama** is comprehensive: full program interface including instructions, errors, and events.
176+
177+
### 4. Supported Languages
178+
179+
| Language | LUMOS | Codama |
180+
|----------|-------|--------|
181+
| Rust | ✅ | ✅ |
182+
| TypeScript | ✅ | ✅ (Solana Kit, Umi) |
183+
| Python | ✅ | ✅ |
184+
| Go | ✅ | ❌ |
185+
| Ruby | ✅ | ❌ |
186+
| Dart | ❌ | ✅ |
187+
188+
### 5. Anchor Integration
189+
190+
**LUMOS:** Context-aware generation. Detects `#[account]` and generates appropriate imports:
191+
192+
```rust
193+
// With #[account] → uses anchor_lang::prelude::*
194+
// Without → uses borsh::{BorshSerialize, BorshDeserialize}
195+
```
196+
197+
**Codama:** Accepts Anchor IDL as input, converts to Codama IDL format, then generates clients.
198+
199+
---
200+
201+
## When to Use Each
202+
203+
### Use LUMOS When:
204+
205+
✅ **Defining new data structures** for a Solana program
206+
✅ **Need Rust + TypeScript type synchronization** with Borsh
207+
✅ **Building new programs** and want a single source of truth
208+
✅ **Want compile-time guarantees** that types match across languages
209+
✅ **Need Go or Ruby** code generation
210+
211+
### Use Codama When:
212+
213+
✅ **Building clients** for existing/deployed programs
214+
✅ **Need full SDK generation** with instruction builders
215+
✅ **Want Dart support** or Umi framework integration
216+
✅ **Generating documentation** for your program
217+
✅ **Need CLI tools** for program interaction
218+
219+
### Decision Matrix
220+
221+
| Your Situation | Recommendation |
222+
|----------------|----------------|
223+
| "I'm starting a new Solana program" | Start with **LUMOS** for data schemas |
224+
| "I need to call an existing program" | Use **Codama** to generate clients |
225+
| "I want type-safe Rust + TS structs" | Use **LUMOS** |
226+
| "I need a full client SDK with all instructions" | Use **Codama** |
227+
| "I'm using Anchor and need clean account structs" | Use **LUMOS** |
228+
| "I want to publish an SDK for my program" | Use **Codama** |
229+
230+
---
231+
232+
## Using Both Together
233+
234+
LUMOS and Codama can work together in a complete development workflow:
235+
236+
### Combined Workflow
237+
238+
```
239+
┌─────────────────────────────────────────────────────────────┐
240+
│ PHASE 1: Define Data Structures (LUMOS) │
241+
│ │
242+
│ schema.lumos → lumos generate → generated.rs + generated.ts│
243+
└─────────────────────────────────────────────────────────────┘
244+
▼
245+
┌─────────────────────────────────────────────────────────────┐
246+
│ PHASE 2: Build Program (Anchor/Native) │
247+
│ │
248+
│ Use generated.rs in your program + write instructions │
249+
└─────────────────────────────────────────────────────────────┘
250+
▼
251+
┌─────────────────────────────────────────────────────────────┐
252+
│ PHASE 3: Deploy & Generate Clients (Codama) │
253+
│ │
254+
│ Deploy program → Parse IDL → Generate full client SDKs │
255+
└─────────────────────────────────────────────────────────────┘
256+
```
257+
258+
### Example Project Structure
259+
260+
```
261+
my-solana-project/
262+
├── schemas/
263+
│ └── accounts.lumos # LUMOS source of truth
264+
├── programs/my-program/
265+
│ └── src/
266+
│ ├── state/
267+
│ │ └── generated.rs # Generated by LUMOS
268+
│ └── lib.rs # Your instruction logic
269+
├── clients/
270+
│ ├── typescript/ # Generated by Codama (full SDK)
271+
│ ├── python/ # Generated by Codama
272+
│ └── rust/ # Generated by Codama
273+
└── app/
274+
└── src/
275+
└── types.ts # Generated by LUMOS (type definitions)
276+
```
277+
278+
### When This Makes Sense
279+
280+
1. **LUMOS for internal type safety:** Your team uses LUMOS to ensure Rust and TypeScript types stay synchronized during development.
281+
282+
2. **Codama for external distribution:** When you're ready to publish, use Codama to generate comprehensive client SDKs with instruction builders, error handling, and documentation.
283+
284+
---
285+
286+
## Summary Comparison Table
287+
288+
| Aspect | LUMOS | Codama |
289+
|--------|-------|--------|
290+
| **Philosophy** | Schema-first | IDL-centric |
291+
| **Direction** | Schema → Code | Program → Clients |
292+
| **Stage** | Pre-deployment | Post-deployment |
293+
| **Focus** | Data structures | Full program interface |
294+
| **Input** | `.lumos` files | Programs / Anchor IDL |
295+
| **Output** | Rust + TS structs | Client SDKs |
296+
| **Rust** | ✅ | ✅ |
297+
| **TypeScript** | ✅ | ✅ (Solana Kit, Umi) |
298+
| **Python** | ✅ | ✅ |
299+
| **Go** | ✅ | ❌ |
300+
| **Ruby** | ✅ | ❌ |
301+
| **Dart** | ❌ | ✅ |
302+
| **Instructions** | ❌ | ✅ |
303+
| **Error types** | ❌ | ✅ |
304+
| **CLI generation** | ❌ | ✅ |
305+
| **Complexity** | Simple, focused | Comprehensive |
306+
307+
---
308+
309+
## Conclusion
310+
311+
**LUMOS and Codama solve different problems at different stages:**
312+
313+
- **LUMOS** = "I want type-safe data structures for my program"
314+
- **Codama** = "I want client SDKs to interact with a program"
315+
316+
They're complementary tools. Use LUMOS when defining your data schemas during development. Use Codama when generating client libraries for distribution.
317+
318+
**Get started:**
319+
- [LUMOS Installation →](/getting-started/installation/)
320+
- [Codama Repository →](https://github.com/codama-idl/codama)

0 commit comments

Comments
 (0)