Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

Declarative CBOR schema via annotations (CborId)

Đang mở
  • Có gì không ổn?
#190 3 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức phù hợp với người mới
30/100
Loại issue
Tính năng
Độ rõ ràng
Khá rõ ràng
Mức độ hoạt động
Đình trệ
Công nghệ
typescript
Lĩnh vực
backend

Hướng nghiên cứu

Bắt đầu trong CBOR.ts bằng cách đọc các kiểu chú thích CborId được đề xuất và thiết kế của codec engine, sau đó kiểm tra các triển khai FromCDDL và CDDLSchema hiện có cho TransactionBody, TransactionWitnessSet và Transaction. Hoàn thành nghĩa là chuyển đổi tất cả các module áp dụng được, bao quát các tập Tag-258, tính hai dạng map/array của redeemer, các map lồng nhau, các trường tùy chọn và việc bảo toàn encoding, đồng thời duy trì khả năng tương thích ngược.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

enhancement exploration

Summary

Replace hand-written FromCDDL transforms with declarative schema annotations that describe CBOR wire format directly on Effect Schema types.

Motivation

Currently each module (TransactionBody, TransactionWitnessSet, Transaction, etc.) has:

  • A CDDLSchema (intermediate CBOR AST type)
  • A FromCDDL transform (hand-written 200-500 line encode/decode)
  • A FromCBORBytes that composes FromBytes with FromCDDL

This creates a two-hop pipeline (Uint8Array → CBOR AST → domain) with a validation boundary that clones objects and strips Symbol metadata (e.g. kEncoding for encoding preservation).

Proposal

A CborId Symbol annotation on Effect Schemas that carries CBOR layout metadata:

const CborId = Symbol.for("evolution/CborId")

const Address = Schema.Uint8ArrayFromSelf.annotations({
  [CborId]: { tag: 259 }
})

const Value = Schema.Struct({
  coin: Schema.BigIntFromSelf,
  multiasset: Schema.optional(MultiAsset),
}).annotations({
  [CborId]: { encoding: "array", fieldOrder: ["coin", "multiasset"] }
})

const TransactionOutput = Schema.Struct({
  address: Address,
  value: Value,
  datum: Schema.optional(Datum),
  scriptRef: Schema.optional(ScriptRef),
}).annotations({
  [CborId]: { encoding: "map", keys: { address: 0n, value: 1n, datum: 2n, scriptRef: 3n } }
})

A generic CBOR codec engine reads [CborId] annotations to:

  • Map struct fields to integer-keyed CBOR map entries or positional array slots
  • Wrap values in CBOR tags (e.g. #6.258 for sets)
  • Handle optional fields (omit from map when undefined)
  • Thread kEncoding preservation metadata automatically

Benefits

  • Eliminates FromCDDL — no hand-written encode/decode per module
  • Eliminates CDDLSchema — domain schema IS the codec schema, no intermediate type
  • Encoding preservation is free — single transform boundary, no clone/Symbol stripping
  • Self-documenting — annotations describe the wire format directly
  • Less code — TransactionBody goes from ~500 lines of transform to ~25 lines of annotated schema

Scope

  • Build CborId annotation types and codec engine in CBOR.ts (~200-400 lines)
  • Convert all modules with FromCDDL transforms to use annotated schemas
  • Handle edge cases: Tag-258 sets, redeemer map/array duality, nested maps, etc.
  • Maintain backward compatibility with existing domain types

Context

Discovered during CBOR encoding preservation work. The immediate fix (replacing MapFromSelf/Tuple CDDLSchemas with non-cloning Schema.declare) unblocks encoding preservation. This issue tracks the larger architectural improvement.

Ngôn ngữ chính
TypeScript
Star
22
Fork
33
Merge trung bình
2 ngày 7 giờ
Pull request đã merge (30 ngày)
39

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của IntersectMBO/evolution-sdk

Tất cả issue của IntersectMBO/evolution-sdk

Issue tương tự

Thêm issue về TypeScript

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.