Codama

Codama là phương pháp nhanh nhất để tạo ra các client an toàn về kiểu cho các chương trình Solana cho nhiều ngôn ngữ và framework, tạo ra các công cụ CLI và cung cấp các thông tin phong phú về chương trình cho các trình khám phá explorer.

Mọi thứ đều bắt đầu với Codama IDL — một định dạng tiêu chuẩn mô tả bất kỳ chương trình Solana nào và là nền tảng cho việc tạo ra tất cả các công cụ liên quan đến chương trình.

Từ một Codama IDL đơn lẻ, bạn có thể tạo ra:

• Các client an toàn về kiểu cho JavaScript, Rust, Python và nhiều ngôn ngữ khác
• Các công cụ CLI để tương tác với chương trình của bạn
• Tài liệu đảm bảo đồng bộ với mã của bạn
• Tích hợp với các trình khám phá để hiểu cấu trúc của chương trình của bạn
• Các công cụ kiểm tra biết rõ giao diện chương trình của bạn

Codama loại bỏ những công việc phiền phức của việc duy trì các client trên nhiều ngôn ngữ và framework.

Thay vì phải viết và cập nhật mã của client mỗi lần chương trình của bạn thay đổi, bạn mô tả chương trình của bạn một lần bằng định dạng Codama IDL, áp dụng bất kỳ biến đổi cần thiết nào bằng cách sử dụng các bộ truy vấn, và tạo ra tất cả những thứ khác tự động

Các khái niệm cốt lõi

Kiến trúc của Codama xoay quanh ba khái niệm cốt lõi: Nodes, Visitors và Renderers.

Các Node

Mọi thứ trong Codama được biểu diễn dưới dạng cây chứa các node. Một node là một đối tượng dữ liệu có cấu trúc mô tả một khía cạnh cụ thể của chương trình Solana của bạn.

Chương trình của bạn trở thành một cây phân cấp bắt đầu với một RootNode ở đầu.

Có các loại node khác nhau:

• Structure Nodes (RootNode, ProgramNode, AccountNode, InstructionNode, ...): Định nghĩa khung chương trình của bạn
• Type Nodes (NumberTypeNode, StringTypeNode, StructTypeNode, ArrayTypeNode): Mô tả cấu trúc dữ liệu và kiểu dữ liệu của các trường
• Value Nodes (NumberValueNode, StringValueNode): thể hiện giá trị mặc định và hằng số

Mỗi loại node phục vụ cho một mục đích đặc biệt và cung cấp một giao diện nhất quán để biểu diễn dữ liệu của nó. Các bộ truy vấn cụ thể cho mỗi ngôn ngữ có thể duyệt và chuyển đổi các node này thành các biểu diễn thích hợp cho các ngôn ngữ mục tiêu khác nhau, cho phép bạn xây dựng các mô tả chương trình phức tạp bằng cách kết hợp các node đơn giản.

Visitors

Visitors là các hàm duyệt qua cây node của bạn để phân tích hoặc chuyển đổi nó.

Chúng thực hiện mô hình truy vấn bằng cách "truy cập" mỗi node trong cây của bạn và thực hiện một số hoạt động trên chúng.

Có hai loại visitors:

Hai loại visitors:

• Analysis Visitors (chỉ đọc): Duyệt qua các node và trả về thông tin bằng codama.accept()
• Transformation Visitors: Duyệt qua các node và trả về một cây đã sửa đổi bằng codama.update()

Visitors tách biệt những gì chương trình của bạn là (các node) từ những gì bạn muốn làm với nó (các hoạt động). Điều này có nghĩa là bạn có thể áp dụng các biến đổi giống nhau cho bất kỳ Codama IDL nào, bất kể cách nó được tạo ra.

Renderers

Renderers là các hàm truy vấn mà chuyển đổi Codama IDL của bạn thành mã client cho các ngôn ngữ lập trình cụ thể.

Mỗi renderer duyệt qua các node của IDL và tạo ra các tệp mã, các kiểu và giao diện phù hợp cho ngôn ngữ mục tiêu của nó.

Để sử dụng một renderer, cung cấp thư mục cơ sở nơi các tệp đã tạo ra được lưu trữ, cùng với các tùy chọn cấu hình để tùy chỉnh đầu ra:

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', { ... }));

Hiện tại chỉ có các renderers sau đây được cung cấp: renderJavaScriptVisitor (tương thích với @solana/kit), renderJavaScriptUmiVisitor (tương thích với @metaplex-foundation/umi và @solana/web3.js) và renderRustVisitor.

Cài đặt

Cài đặt gói cơ sở của Codama bằng trình quản lý gói của bạn:

pnpm install codama

Việc này bao gồm cả các gói @codama/visitors và @codama/nodes, cung cấp mọi thứ bạn cần để tạo và điều chỉnh các IDLs.

Các gói riêng lẻ như @codama/visitors và @codama/nodes có thể được cài đặt riêng biệt nếu bạn muốn kiểm soát chi tiết hơn về các phần phụ thuộc.

Để tạo ra mã client, bạn cũng cần gói renderers:

pnpm install codama @codama/renderers

Gói renderers được phân phối riêng biệt vì nó yêu cầu truy cập hệ thống tệp và chỉ hoạt động trong môi trường Node.js, trong khi thư viện cơ sở của Codama chạy mọi nơi (Node.js, trình duyệt, v.v.).

Cấu hình

Codama cung cấp một giao diện dòng lệnh mà đơn giản hóa cách làm việc với các IDL và tạo mã client. Giao diện dòng lệnh quản lý cấu hình và thực thi các tập lệnh, giúp bạn dễ dàng thiết lập các luồng làm việc tự động.

Cài đặt gói CLI và khởi tạo dự án của bạn:

pnpm install @codama/cli
pnpm codama init

Lệnh init sẽ hỏi bạn:

• Đường dẫn đến tệp IDL của bạn (hỗ trợ cả Codama và Anchor IDLs)
• Các mẫu mà bạn muốn sử dụng (JavaScript, Rust, v.v.)

Việc này tạo ra một tệp cấu hình mà định nghĩa IDL nguồn và các script và trông như sau:

{
    "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"] }
        ]
    }
}

Phần before chứa các Visitors chạy trước mỗi script (cho các biến đổi, dọn dẹp, v.v.) và phần scripts chứa các Renderers được sử dụng để tạo ra các client

Bạn có thể thực hiện các script đã cấu hình của mình bằng lệnh 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

Không sử dụng CLI

Nếu bạn không muốn sử dụng CLI, bạn có thể tạo ra một tệp codama.ts trong kho lưu trữ của mình, chỉ định logic Codama IDL của bạn (nhập, truy vấn và renderers) và sau đó chạy:

pnpx tsx codama.ts