Skip to main content

CIP-0029

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)

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"

CC-BY-4.0

CIP Information

This Standards ./CIP-0029 created on 2020-08-17 has the status: Active.
This page was generated automatically from: cardano-foundation/CIPs.