IntersectMBO / IntersectMBO/evolution-sdk

Declarative CBOR schema via annotations (CborId)

Aperta
#190 3 commenti 0 reazioni 0 assegnatari Vedi su GitHub
enhancement exploration
Lingua principale
TypeScript
Stelle
22
Fork
30
Merge medio
5h 29m
PR unite (30g)
12

Descrizione

## 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.

Guida per i contributori

Apri la guida per i contributori

Direzione di ricerca

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.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Valutazione

Stack tecnologico
typescript
Ambito
backend
Tipo di issue
Funzionalità
Difficoltà
5/5
Tempo stimato
Più di una settimana
Stato di attività
Ferma
Chiarezza
Abbastanza chiara
Idoneità per principianti
30/100

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.