IntersectMBO / IntersectMBO/evolution-sdk
Declarative CBOR schema via annotations (CborId)
- Vorherrschende Sprache
- TypeScript
- Sterne
- 22
- Forks
- 30
- Ø Merge
- 5 Std. 29 Min.
- Gemergte PRs (30 T.)
- 12
Beschreibung
## 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:
```ts
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.
Beitragsleitfaden
Rechercherichtung
Start in CBOR.ts by reading the proposed CborId annotation types and codec engine design, then inspect the existing FromCDDL and CDDLSchema implementations for TransactionBody, TransactionWitnessSet, and Transaction. Done means converting all applicable modules, covering Tag-258 sets, redeemer map/array duality, nested maps, optional fields, and encoding preservation while maintaining backward compatibility.
Vom Indexierungsmodell aus dem Issue-Text verfasst.
Bewertung
- Tech-Stack
- typescript
- Bereich
- backend
- Issue-Typ
- Feature
- Schwierigkeit
- 5/5
- Geschätzter Aufwand
- Über eine Woche
- Aktivitätsstatus
- Veraltet
- Klarheit
- Größtenteils klar
- Anfängerfreundlichkeit
- 30/100