CIP-0029 | Phase-1 Monetary Scripts Serialization Formats

[KtorZ]

Abstract

This specification describes how to serialize Phase-1 monetary scripts (a.k.a. "native scripts") to various formats (JSON, CBOR) to facilitate inter-operability between applications.

Motivation

While the existence of scripts is well-known, and have an unambiguous on-chain representation. There's no agreed upon format for off-chain or higher-level interfaces for which a binary string is a poor fit. This CIP regroups both the on-chain binary format and other, more verbose, formats like JSON.

Specification

This specification covers at present two serialization formats: JSON and CBOR. The CBOR matches exactly the on-chain representation and is extracted from the cardano-ledger-specs source code and put here as a convenient place to lookup while the source can change location over time.

CBOR

The CBOR serialization format is given as a CDDL specification in annexe. When a hash of the phase-1 monetary script is needed, it usually refers to a Blake2b-192 digest of the corresponding serialized script byte-string prefixed with a null byte: \x00.

JSON

The JSON format is given as a JSON schema in annexe. It is preferred in user interfaces such as command-lines or APIs, where some level of human inspection may be required.

Notes

• Scripts may contain unbounded integers! Implementation parsing them, either from CBOR or JSON shall be prepared to handle possible big integers (>= 2^64).

Rationale

• The preimage for computing script hashes is prefixed with \x00 to distinguish them from phase-2 monetary scripts (a.k.a Plutus Script) which are then prefixed with \x01. This is merely a discriminator tag.

• The current JSON format is based off the cardano-cli's format which has been used widely for minting tokens and is likely the most widely accepted format at the moment.

Backward Compatibility

N/A

Reference Implementation(s)

• cardano-cli & cardano-api

Test Vectors

- json:
    { "type": "sig"
    , "keyHash": "00000000000000000000000000000000000000000000000000000000"
    }
  cbor: 
    "8200581c00000000000000000000000000000000000000000000000000000000"
    
- json:
    { "type": "all"
    , "scripts":
      [ { "type": "sig"
        , "keyHash": "00000000000000000000000000000000000000000000000000000000"
        }
      , { "type": "any"
        , "scripts": 
          [ { "type": "after"
            , "slot": 42
            }
          , { "type": "sig"
            , "keyHash": "00000000000000000000000000000000000000000000000000000001"
            }
          ]
        }
      ]
    }
  cbor:
    "8201828200581c000000000000000000000000000000000000000000000000000000008202828204182a8200581c00000000000000000000000000000000000000000000000000000001"

- json:
    { "type": "before"
    , "slot": 42
    }
  cbor: 
    "8205182a"

- json:
    { "type": "atLeast"
    , "required": 2
    , "scripts":
      [ { "type": "sig", "keyHash": "00000000000000000000000000000000000000000000000000000000" }
      , { "type": "sig", "keyHash": "00000000000000000000000000000000000000000000000000000001" }
      , { "type": "sig", "keyHash": "00000000000000000000000000000000000000000000000000000002" }
      ]
    }
  cbor:
    "00830302838200581c000000000000000000000000000000000000000000000000000000008200581c000000000000000000000000000000000000000000000000000000018200581c00000000000000000000000000000000000000000000000000000002"

Copyright

CC-BY-4.0

[dcoutts]

I think it's great to document the JSON and CBOR representations together in one place.

[dcoutts]

These are backwards compared to the Allegra & Mary CDDL spec.

[KtorZ]

What do you mean with backward? I've tried to keep the terminology the same as the one used in the cardano-api. The cddl calls them "invalid before" and "invalid hereafter"

[dcoutts]

The numbers are backwards compared to the Allegra & Mary CDDL spec.

invalid_before = (4, uint)
invalid_hereafter = (5, uint)

From the overall:

native_script =
  [ script_pubkey
  // script_all
  // script_any
  // script_n_of_k
  // invalid_before
     ; Timelock validity intervals are half-open intervals [a, b).
     ; This field specifies the left (included) endpoint a.
  // invalid_hereafter
     ; Timelock validity intervals are half-open intervals [a, b).
     ; This field specifies the right (excluded) endpoint b.
  ]

script_pubkey = (0, addr_keyhash)
script_all = (1, [ * native_script ])
script_any = (2, [ * native_script ])
script_n_of_k = (3, n: uint, [ * native_script ])
invalid_before = (4, uint)
invalid_hereafter = (5, uint)

[KtorZ]

I think the number are correct, but the terminology is confusing. While the CDDL on cardano-ledger-specs speaks about invalid before for tag 4 (resp. invalid after for tag 5), this CIP CDDL (which uses the same terminology as the cardano-api) speaks about valid after for tag 4 (resp. valid before for tag 5).

From cardano-api:

  toJSON (RequireTimeAfter _ slot) =
    object [ "type" .= String "after"
           , "slot" .= slot
           ]

and

    go (RequireTimeAfter  _ t) = Timelock.RequireTimeStart  t

and from cardano-ledger-specs

pattern RequireTimeStart mslot <-
  TimelockConstr (Memo (TimeStart mslot) _)

encRaw (TimeStart m) = Sum TimeStart 4 !> To m

Thus, the JSON "after" corresponds to tag 4 in CDDL, but "after" really means valid after in this context.

I agree that the discrepancy is unfortunate, and in my opinion, it should be fixed in the CDDL (since it's only a terminology change, whereas changing it in the JSON interface would be backward incompatible), and that's why I chose to stick with the cardano-api's JSON terminology in this proposal as well.

[crptmppt]

This PR was discussed at the last Editors meeting and is tentatively flagged as 'Last Check'. Please refer to meeting 31 notes for details, or join us for next week's meeting 32 (Tuesday)

[crptmppt]

Merged in as noted in CIP Editors meeting 32