Cardano Improvement Proposals


CIP 29 - Phase-1 Monetary Scripts Serialization Formats

Contents

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

Rationale

Backward Compatibility

N/A

Reference Implementation(s)

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