Skip to content

Latest commit

 

History

History
42 lines (24 loc) · 1.97 KB

js-cbor-mapping.md

File metadata and controls

42 lines (24 loc) · 1.97 KB

JS to Canonical CBOR Mapping

Define how host-side JavaScript values become deterministic ABI bytes.

Depends on:

Purpose

At the ABI boundary, bytes are the identity surface. JavaScript values have ambient behaviors that are not deterministic enough for hashing, replay, or ledger stamping. This packet defines the allowed mapping into canonical CBOR.

Host-adapter bugs must fail before they enter the kernel. Malformed or non-canonical values are rejected with a clear ABI error instead of being normalized differently by different hosts.

Payload construction is deterministic: encoding the same logical value twice produces byte-identical CBOR before intent or observation submission.

Decision 1: The supported scalar mapping is narrow

null, booleans, strings, safe integral numbers, and canonical floats are allowed. undefined and BigInt are rejected for the current ABI mapping.

Decision 2: Bytes and arrays are definite-length only

Uint8Array maps to a definite-length byte string. JS arrays map to definite-length arrays with recursively encoded elements. Indefinite-length CBOR is never accepted or emitted.

Decision 3: Objects map to sorted string-key maps

Object keys must be strings. Encoded map keys are sorted by their CBOR byte encoding, not insertion order. Duplicate keys, non-string keys, unknown fields, and missing required fields are schema errors.

Decision 4: Prohibited CBOR features stay prohibited

The ABI mapping does not use tags, indefinite-length values, non-shortest integer encodings, or non-canonical float encodings.

Decision 5: Canonical bytes are payload identity

The bytes produced by this mapping are the bytes used for hashing, ledger identity, EINT payloads, and observation requests.