Codama 101

Codama — це найшвидший спосіб створення типобезпечних клієнтів для програм Solana на різних мовах програмування та фреймворках, створення інструментів CLI та надання детальної інформації про програми для експлорерів.

Все починається з Codama IDL — стандартизованого формату, який описує будь-яку програму Solana і служить основою для створення всіх інструментів, пов'язаних з програмою.

З одного Codama IDL ви можете створити:

Типобезпечні клієнти для JavaScript, Rust, Python та інших мов
Інструменти CLI для взаємодії з вашою програмою
Документацію, яка синхронізується з вашим кодом
Інтеграції з експлорерами, які розуміють структуру вашої програми
Інструменти тестування, які знають інтерфейс вашої програми

Codama усуває рутинну роботу з підтримки клієнтів на різних мовах програмування та фреймворках.

Замість того, щоб вручну писати та оновлювати клієнтський код щоразу, коли ваша програма змінюється, ви описуєте свою програму один раз у форматі Codama IDL, застосовуєте необхідні перетворення за допомогою відвідувачів і автоматично генеруєте все інше

Основні концепції

Архітектура Codama обертається навколо трьох фундаментальних концепцій: вузли, відвідувачі та рендерери.

Вузли

Все в Codama представлено як дерево вузлів. Вузол — це структурований об'єкт даних, який описує один конкретний аспект вашої програми Solana.

Вся ваша програма стає ієрархічним деревом, яке починається з RootNode на верхньому рівні.

Існують різні типи вузлів:

Структурні вузли (RootNode, ProgramNode, AccountNode, InstructionNode, ...): Визначають скелет вашої програми
Вузли типів (NumberTypeNode, StringTypeNode, StructTypeNode, ArrayTypeNode): Описують структури даних і типи полів
Вузли значень (NumberValueNode, StringValueNode): Представляють значення за замовчуванням і константи

Кожен тип вузла виконує конкретну функцію та надає уніфікований інтерфейс для представлення своїх даних. Відвідувачі, специфічні для кожної мови, можуть потім обходити та перетворювати ці вузли у відповідні представлення для різних цільових мов, дозволяючи вам будувати складні описи програм шляхом комбінування простих вузлів.

Відвідувачі

Відвідувачі — це функції, які обходять дерево вузлів для його аналізу або перетворення.

Вони реалізують патерн відвідувача, "відвідуючи" кожен вузол у вашому дереві та виконуючи над ними операції.

Існує 2 типи відвідувачів:

Аналітичні відвідувачі (лише для читання): Обходять вузли та повертають інформацію за допомогою codama.accept()
Трансформаційні відвідувачі: Обходять вузли та повертають модифіковане дерево за допомогою codama.update()

Відвідувачі відокремлюють те, чим є ваша програма (вузли), від того, що ви хочете з нею робити (операції). Це означає, що ви можете застосовувати однакові перетворення до будь-якого Codama IDL, незалежно від того, як він був створений.

Рендерери

Рендерери — це функції-відвідувачі, які перетворюють ваш Codama IDL на клієнтський код для конкретних мов програмування.

Кожен рендерер обходить вузли IDL і генерує відповідні файли коду, типи та інтерфейси для своєї цільової мови.

Щоб використовувати рендерер, вкажіть базовий каталог, де мають зберігатися згенеровані файли, разом з додатковою конфігурацією для налаштування виводу:

ts
import { createFromRoot, programNode, rootNode } from 'codama';
import { renderJavaScriptVisitor, renderRustVisitor } from '@codama/renderers';
 
// Create or import your Codama IDL.
const codama = createFromRoot(rootNode(programNode({ ... })));
 
// Render SDKs from your IDL.
codama.accept(renderJavaScriptVisitor('clients/js/src/generated', { ... }));
codama.accept(renderRustVisitor('clients/rust/src/generated', { ... }));

На даний момент доступні лише такі рендерери: renderJavaScriptVisitor (сумісний з @solana/kit), renderJavaScriptUmiVisitor (сумісний з @metaplex-foundation/umi та @solana/web3.js) та renderRustVisitor.

Installation

Встановіть основний пакет Codama за допомогою вашого улюбленого менеджера пакетів:

pnpm install codama

Це включає пакети @codama/visitors та @codama/nodes, надаючи все необхідне для створення та маніпулювання IDL.

Окремі пакети, такі як @codama/visitors та @codama/nodes, можна встановити окремо, якщо ви віддаєте перевагу детальному контролю над залежностями.

Для генерації клієнтського коду вам також знадобиться пакет рендерерів:

pnpm install codama @codama/renderers

Пакет рендерерів розповсюджується окремо, оскільки він потребує доступу до файлової системи і працює лише в середовищах Node.js, тоді як основна бібліотека Codama працює всюди (Node.js, браузери тощо).

Налаштування

Codama надає інтерфейс командного рядка (CLI), який спрощує роботу з IDL та генерацію клієнтського коду. CLI керує конфігурацією та виконанням скриптів, полегшуючи налаштування автоматизованих робочих процесів.

Встановіть пакет CLI та ініціалізуйте ваш проєкт:

pnpm install @codama/cli
pnpm codama init

Команда init запитає у вас:

Шлях до вашого IDL-файлу (підтримує як Codama, так і Anchor IDL)
Пресети скриптів, які ви хочете використовувати (JavaScript, Rust тощо)

Це створює конфігураційний файл, який визначає джерело вашого IDL та скрипти генерації, і виглядає так:

json
{
    "idl": "path/to/your/idl",
    "before": [
        "./custom-transforms.js",
        { "from": "@codama/visitors#removeTypes", "args": [["internal"]] }
    ],
    "scripts": {
        "js": [
            { "from": "@codama/renderers-js", "args": ["clients/js/src"] }
        ],
        "rust": [
            { "from": "@codama/renderers-rust", "args": ["clients/rust/src"] }
        ]
    }
}

before містить Visitors, які виконуються перед кожним скриптом (для трансформацій, очищення тощо), а scripts містить Renderers, які використовуються для генерації клієнтів

Ви можете виконати налаштовані скрипти за допомогою команди run:

pnpm codama run              # Run preparation steps only
pnpm codama run js rust      # Run specific language generators
pnpm codama run --all        # Run all configured scripts

Без CLI

Якщо ви не хочете використовувати CLI, ви можете створити файл codama.ts у вашому репозиторії, вказати логіку Codama IDL (імпорти, відвідувачі та рендерери), а потім виконати:

pnpx tsx codama.ts

Створення SDK з Codama