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

Phase-1 Monetary Scripts Serialization Formats