Skip to content

Improve and shorten Introduction #95

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
fxamacker merged 1 commit into from
Aug 4, 2023
Merged

Improve and shorten Introduction #95

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 7 additions & 11 deletions ccf_specs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
Author: Faye Amacker
Status: RC2 DRAFT
Date: August 3, 2023
Revision: 20230803a
Revision: 20230803b

## Abstract

Expand Down Expand Up @@ -42,21 +42,13 @@ Cadence external values (e.g. events, transaction arguments, etc.) have been enc
The same `FeesDeducted` event on the Flow blockchain can encode to:
- 298 bytes in JSON-CDC (minified).
- 118 bytes in CCF (fully self-describing mode).
- 20 bytes in CCF (partially self-describing mode).
-  20 bytes in CCF (partially self-describing mode).

CCF defines all requirements for deterministic encoding (sort orders, smallest encoded forms, and Cadence-specific requirements) to allow CCF codecs implemented in different programming languages to produce the same deterministic encodings.

Some requirements (such as "Deterministic CCF Encoding Requirements") are defined as optional. Each CCF-based format or protocol can have its specification state how CCF options are used. This allows each protocol to balance tradeoffs such as compatibility, determinism, speed, encoded data size, etc.

CCF leverages [Internet Standards](https://en.wikipedia.org/wiki/Internet_Standard) from [IETF](https://www.ietf.org) which are designed to be relevant for decades:

- [RFC 8949](https://www.rfc-editor.org/rfc/rfc8949.html) defines the Concise Binary Object Representation (CBOR). CBOR is a stable, efficient, and extensible data format. CBOR is used by other standards such as W3C WebAuthn, IETF COSE (RFC 9052), and IETF CWT (RFC 8392).

- [RFC 8610](https://www.rfc-editor.org/rfc/rfc8610.html) defines the Concise Data Definition Language (CDDL). CDDL is a notation for unambiguously expressing CBOR and JSON data structures.

- [Appendix G of RFC 8610](https://www.rfc-editor.org/rfc/rfc8610.html#appendix-G) defines the Extended Diagnostic Notation. EDN is a "diagnostic notation" used for conversing about encoded CBOR data items.

CBOR is used by CCF to deterministically encode values to their smallest form. CDDL notation is used in this document to define CCF. EDN is used to describe encoded examples.
This specification uses CBOR, an [Internet Standard](https://www.ietf.org/rfc/std-index.txt) defined by [IETF STD 94](https://www.rfc-editor.org/info/std94). CBOR is designed to be relevant for decades and is used by data formats and protocols such as [W3C WebAuthn](https://www.w3.org/TR/webauthn-2/), C-DNS ([IETF RFC 8618](https://www.rfc-editor.org/rfc/rfc8618.html)), COSE ([IETF STD 96](https://www.rfc-editor.org/info/std96)), CWT ([IETF RFC 8392](https://www.rfc-editor.org/info/rfc8392)), etc.

### Objectives

Expand Down Expand Up @@ -144,6 +136,10 @@ In Go, [fxamacker/cbor](https://github.com/fxamacker/cbor) is used by Cadence in

This specification uses requirements terminology, CBOR terminology, and CDDL terminology.

This specification uses the following notations to specify or describe CCF:
- Concise Data Definition Language (CDDL) defined by [RFC 8610](https://www.rfc-editor.org/rfc/rfc8610.html). CDDL is a notation for unambiguously expressing CBOR and JSON data structures.
- Extended Diagnostic Notation (EDN) defined by [Appendix G of RFC 8610](https://www.rfc-editor.org/rfc/rfc8610.html#appendix-G). EDN is a "diagnostic notation" used for conversing about encoded CBOR data items.

#### Requirements Terminology

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [[RFC2119](https://www.rfc-editor.org/info/rfc2119)] [[RFC8174](https://www.rfc-editor.org/info/rfc8174)] when, and only when, they appear in all capitals, as shown here.
Expand Down