From cd585c94c6bc425aba42431fa75398016f35633c Mon Sep 17 00:00:00 2001 From: Vladimir Kalnitsky Date: Fri, 26 Jan 2024 19:55:16 +0400 Subject: [PATCH 01/61] JSON-spec: add specs for numeric types --- CIP-XXXX/schema.json | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) create mode 100644 CIP-XXXX/schema.json diff --git a/CIP-XXXX/schema.json b/CIP-XXXX/schema.json new file mode 100644 index 0000000000..523d3fe363 --- /dev/null +++ b/CIP-XXXX/schema.json @@ -0,0 +1,34 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "cardano.json", + "title": "Cardano Domain Types", + "definitions": { + "BigInt": { + "title": "BigInt", + "type": "string", + "description": "A long integer domain type", + "pattern": "^-?(0|[1-9][0-9]*)$", + "examples": [ + "0", + "-123", + "123" + ] + }, + "BigNum": { + "type": "string", + "pattern": "^-?(0|[1-9][0-9]*)$", + "format": "uint64" + }, + "Int": { + "type": "string", + "pattern": "^-?(0|[1-9][0-9]*)$", + "format": "int128" + }, + "UInt": { + "type": "integer", + "pattern": "^(0|[1-9][0-9]*)$", + "minimum": 0, + "maximum": 4294967295 + } + } +} From 88fc4c9918cb92412a91166e757f8d0b3617d428 Mon Sep 17 00:00:00 2001 From: Vladimir Kalnitsky Date: Fri, 26 Jan 2024 23:44:09 +0400 Subject: [PATCH 02/61] Add Address types and PlutusData --- CIP-XXXX/schema.json | 116 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 116 insertions(+) diff --git a/CIP-XXXX/schema.json b/CIP-XXXX/schema.json index 523d3fe363..0da561722a 100644 --- a/CIP-XXXX/schema.json +++ b/CIP-XXXX/schema.json @@ -29,6 +29,122 @@ "pattern": "^(0|[1-9][0-9]*)$", "minimum": 0, "maximum": 4294967295 + }, + "RewardAddress": { + "title": "RewardAddress", + "type": "string", + "contentEncoding": "bech32", + "pattern": "^(addr1|addr_test1)[02-9ac-hj-np-z]*$" + }, + "ByronAddress": { + "title": "ByronAddress", + "type": "string", + "contentEncoding": "base58", + "pattern": "^[1-9A-HJ-NP-Za-km-z]*$" + }, + "PointerAddress": { + "title": "PointerAddress", + "type": "string", + "contentEncoding": "bech32", + "pattern": "^(addr1|addr_test1)[02-9ac-hj-np-z]*$" + }, + "EnterpriseAddress": { + "title": "EnterpriseAddress", + "type": "string", + "contentEncoding": "bech32", + "pattern": "^(addr1|addr_test1)[02-9ac-hj-np-z]*$" + }, + "BaseAddress": { + "title": "BaseAddress", + "type": "string", + "contentEncoding": "bech32", + "pattern": "^(addr1|addr_test1)[02-9ac-hj-np-z]*$" + }, + "Address": { + "title": "Address", + "oneOf": [ + { + "$ref": "cardano.json#/definitions/RewardAddress" + }, + { + "$ref": "cardano.json#/definitions/BaseAddress" + }, + { + "$ref": "cardano.json#/definitions/PointerAddress" + }, + { + "$ref": "cardano.json#/definitions/EnterpriseAddress" + }, + { + "$ref": "cardano.json#/definitions/ByronAddress" + } + ] + }, + "PlutusData": { + "title": "PlutusData", + "oneOf": [ + { + "$ref": "cardano.json#/definitions/PlutusDataConstr", + "$ref": "cardano.json#/definitions/PlutusDataMap", + "$ref": "cardano.json#/definitions/PlutusDataList", + "$ref": "cardano.json#/definitions/PlutusDataInteger", + "$ref": "cardano.json#/definitions/PlutusDataBytes" + } + ] + }, + "PlutusDataList": { + "title": "PlutusDataList", + "type": "array", + "items": { + "$ref": "cardano.json#/definitions/PlutusData" + } + }, + "PlutusDataConstr": { + "title": "PlutusDataConstr", + "properties": { + "alternative": { + "$ref": "cardano.json#/definitions/BigNum" + }, + "data": { + "$ref": "cardano.json#/definitions/PlutusDataList" + } + } + }, + "PlutusDataMap": { + "title": "PlutusDataMap", + "type": "object", + "properties": { + "tag": { + "type": "string", + "enum": ["map"] + }, + "value": { + "type": "array", + "items": { + "type": "object", + "properties": { + "key": { "$ref": "cardano.json#/definitions/PlutusData" }, + "value": { "$ref": "cardano.json#/definitions/PlutusData" } + } + } + } + } + }, + "PlutusDataInteger": { + "type": "object", + "properties": { + "tag": { + "type": "string", + "enum": ["integer"] + }, + "value": { "$ref": "cardano.json#/definitions/BigInt" } + } + }, + "PlutusDataBytes": { + "title": "PlutusDataBytes", + "type": "string", + "contentEncoding": "hex", + "pattern": "^([0-9a-f][0-9a-f])*$" } } } From 345d3cfdc5e0cad0e4d92be426468a02791a706f Mon Sep 17 00:00:00 2001 From: Vladimir Kalnitsky Date: Fri, 26 Jan 2024 23:47:09 +0400 Subject: [PATCH 03/61] Re-implement PlutusData via oneOf --- CIP-XXXX/schema.json | 118 +++++++++++++++++++++++-------------------- 1 file changed, 62 insertions(+), 56 deletions(-) diff --git a/CIP-XXXX/schema.json b/CIP-XXXX/schema.json index 0da561722a..1725c0d892 100644 --- a/CIP-XXXX/schema.json +++ b/CIP-XXXX/schema.json @@ -84,67 +84,73 @@ "title": "PlutusData", "oneOf": [ { - "$ref": "cardano.json#/definitions/PlutusDataConstr", - "$ref": "cardano.json#/definitions/PlutusDataMap", - "$ref": "cardano.json#/definitions/PlutusDataList", - "$ref": "cardano.json#/definitions/PlutusDataInteger", - "$ref": "cardano.json#/definitions/PlutusDataBytes" - } - ] - }, - "PlutusDataList": { - "title": "PlutusDataList", - "type": "array", - "items": { - "$ref": "cardano.json#/definitions/PlutusData" - } - }, - "PlutusDataConstr": { - "title": "PlutusDataConstr", - "properties": { - "alternative": { - "$ref": "cardano.json#/definitions/BigNum" - }, - "data": { - "$ref": "cardano.json#/definitions/PlutusDataList" - } - } - }, - "PlutusDataMap": { - "title": "PlutusDataMap", - "type": "object", - "properties": { - "tag": { - "type": "string", - "enum": ["map"] - }, - "value": { + "title": "PlutusDataList", "type": "array", "items": { - "type": "object", - "properties": { - "key": { "$ref": "cardano.json#/definitions/PlutusData" }, - "value": { "$ref": "cardano.json#/definitions/PlutusData" } + "$ref": "cardano.json#/definitions/PlutusData" + } + }, + { + "title": "PlutusDataConstr", + "properties": { + "alternative": { + "$ref": "cardano.json#/definitions/BigNum" + }, + "data": { + "type": "array", + "items": { + "$ref": "cardano.json#/definitions/PlutusData" + } } } - } - } - }, - "PlutusDataInteger": { - "type": "object", - "properties": { - "tag": { - "type": "string", - "enum": ["integer"] }, - "value": { "$ref": "cardano.json#/definitions/BigInt" } - } - }, - "PlutusDataBytes": { - "title": "PlutusDataBytes", - "type": "string", - "contentEncoding": "hex", - "pattern": "^([0-9a-f][0-9a-f])*$" + { + "title": "PlutusDataMap", + "type": "object", + "properties": { + "tag": { + "type": "string", + "enum": [ + "map" + ] + }, + "value": { + "type": "array", + "items": { + "type": "object", + "properties": { + "key": { + "$ref": "cardano.json#/definitions/PlutusData" + }, + "value": { + "$ref": "cardano.json#/definitions/PlutusData" + } + } + } + } + } + }, + { + "type": "object", + "properties": { + "tag": { + "type": "string", + "enum": [ + "integer" + ] + }, + "value": { + "$ref": "cardano.json#/definitions/BigInt" + } + } + }, + { + "title": "PlutusDataBytes", + "type": "string", + "contentEncoding": "hex", + "pattern": "^([0-9a-f][0-9a-f])*$" + } + ] } } } From b2be44f52a032c2a3c179912de6ac6d53a7b7e7d Mon Sep 17 00:00:00 2001 From: Vladimir Kalnitsky Date: Mon, 29 Jan 2024 13:46:16 +0400 Subject: [PATCH 04/61] Switch to `tag`/`value`-based encoding of PlutusData for ease of programmatic processing --- CIP-XXXX/schema.json | 44 +++++++++++++++++++++++++++++++++++++------- 1 file changed, 37 insertions(+), 7 deletions(-) diff --git a/CIP-XXXX/schema.json b/CIP-XXXX/schema.json index 1725c0d892..a461bdbf0a 100644 --- a/CIP-XXXX/schema.json +++ b/CIP-XXXX/schema.json @@ -85,14 +85,32 @@ "oneOf": [ { "title": "PlutusDataList", - "type": "array", - "items": { - "$ref": "cardano.json#/definitions/PlutusData" + "type": "object", + "properties": { + "tag": { + "type": "string", + "enum": [ + "list" + ] + }, + "contents": { + "type": "array", + "items": { + "$ref": "cardano.json#/definitions/PlutusData" + } + } } }, { "title": "PlutusDataConstr", + "type": "object", "properties": { + "tag": { + "type": "string", + "enum": [ + "constr" + ] + }, "alternative": { "$ref": "cardano.json#/definitions/BigNum" }, @@ -114,7 +132,7 @@ "map" ] }, - "value": { + "contents": { "type": "array", "items": { "type": "object", @@ -131,6 +149,7 @@ } }, { + "title": "PlutusDataInteger", "type": "object", "properties": { "tag": { @@ -146,9 +165,20 @@ }, { "title": "PlutusDataBytes", - "type": "string", - "contentEncoding": "hex", - "pattern": "^([0-9a-f][0-9a-f])*$" + "type": "object", + "properties": { + "tag": { + "type": "string", + "enum": [ + "bytes" + ] + }, + "value": { + "type": "string", + "contentEncoding": "hex", + "pattern": "^([0-9a-f][0-9a-f])*$" + } + } } ] } From b4e91ab58067d9bdac9cf468b3f64c1b868fe7d3 Mon Sep 17 00:00:00 2001 From: Vladimir Kalnitsky Date: Mon, 29 Jan 2024 17:20:25 +0400 Subject: [PATCH 05/61] Add schema for TransactionOutput subtypes --- CIP-XXXX/schema.json | 149 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 147 insertions(+), 2 deletions(-) diff --git a/CIP-XXXX/schema.json b/CIP-XXXX/schema.json index a461bdbf0a..ceb96fae73 100644 --- a/CIP-XXXX/schema.json +++ b/CIP-XXXX/schema.json @@ -4,7 +4,7 @@ "title": "Cardano Domain Types", "definitions": { "BigInt": { - "title": "BigInt", + "title": "Long signed integer", "type": "string", "description": "A long integer domain type", "pattern": "^-?(0|[1-9][0-9]*)$", @@ -15,18 +15,20 @@ ] }, "BigNum": { + "title": "64-bit unsigned integer", "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$", "format": "uint64" }, "Int": { + "title": "128-bit signed integer", "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$", "format": "int128" }, "UInt": { + "title": "32-bit unsigned integer", "type": "integer", - "pattern": "^(0|[1-9][0-9]*)$", "minimum": 0, "maximum": 4294967295 }, @@ -80,6 +82,149 @@ } ] }, + "MultiAsset": { + "title": "MultiAsset", + "description": "A mapping from policy IDs (script hashes) to mappings from asset names to amounts", + "type": "object", + "patternProperties": { + "^[0-9a-f]{56}$": { + "type": "object", + "patternProperties": { + "^([0-9a-f][0-9a-f]){0,32}$": { + "$ref": "cardano.json#/definitions/BigNum" + } + }, + "additionalProperties": false + } + }, + "additionalProperties": false + }, + "Value": { + "title": "Value", + "type": "object", + "properties": { + "coin": { + "$ref": "cardano.json#/definitions/BigNum" + }, + "multiasset": { + "$ref": "cardano.json#/definitions/MultiAsset" + } + } + }, + "TransactionHash": { + "title": "TransactionHash", + "type": "string", + "pattern": "^[0-9a-f]{64}$" + }, + "TransactionInput": { + "type": "object", + "properties": { + "hash": { + "$ref": "cardano.json#/definitions/TransactionHash" + }, + "index": { + "$ref": "cardano.json#/definitions/UInt" + } + } + }, + "PlutusScript": { + "type": "string", + "contentEncoding": "hex", + "pattern": "^([0-9a-f][0-9a-f])+$" + }, + "NativeScript": { + "title": "TODO align with cardano-cli" + }, + "ScriptRef": { + "title": "ScriptRef", + "oneOf": [ + { + "title": "PlutusScript", + "type": "object", + "properties": { + "tag": { + "type": "string", + "enum": [ + "plutus_script" + ] + }, + "value": { + "$ref": "cardano.json#/definitions/PlutusScript" + } + } + }, + { + "title": "NativeScript", + "type": "object", + "properties": { + "tag": { + "type": "string", + "enum": [ + "native_script" + ] + }, + "value": { + "$ref": "cardano.json#/definitions/NativeScript" + } + } + } + ] + }, + "DataHash": { + "title": "DataHash", + "type": "string", + "contentEncoding": "hex", + "pattern": "^([0-9a-f][0-9a-f]){32}$" + }, + "TransactionOutput": { + "title": "TransactionOutput", + "type": "object", + "properties": { + "address": { + "$ref": "cardano.json#/definitions/Address" + }, + "amount": { + "$ref": "cardano.json#/definitions/Value" + }, + "plutus_data": { + "oneOf": [ + { + "type": "object", + "properties": { + "tag": { + "enum": [ + "datum" + ] + }, + "value": { + "$ref": "cardano.json#/definitions/PlutusData" + } + } + }, + { + "type": "object", + "properties": { + "tag": { + "enum": [ + "datum_hash" + ] + }, + "value": { + "$ref": "cardano.json#/definitions/DataHash" + } + } + } + ] + }, + "script_ref": { + "$ref": "cardano.json#/definitions/ScriptRef" + }, + "requiredProperties": [ + "address", + "amount" + ] + } + }, "PlutusData": { "title": "PlutusData", "oneOf": [ From 55a664416942fe199cb4c0847fcd42fb6612f052 Mon Sep 17 00:00:00 2001 From: Vladimir Kalnitsky Date: Mon, 29 Jan 2024 20:58:32 +0400 Subject: [PATCH 06/61] Add TransactionMetadatum --- CIP-XXXX/schema.json | 110 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 110 insertions(+) diff --git a/CIP-XXXX/schema.json b/CIP-XXXX/schema.json index ceb96fae73..28c31b0f78 100644 --- a/CIP-XXXX/schema.json +++ b/CIP-XXXX/schema.json @@ -14,6 +14,13 @@ "123" ] }, + "ByteString": { + "title": "ByteString", + "description": "Arbitrary-length byte array", + "type": "string", + "contentEncoding": "hex", + "pattern": "^([0-9a-f][0-9a-f])+$" + }, "BigNum": { "title": "64-bit unsigned integer", "type": "string", @@ -225,6 +232,109 @@ ] } }, + "TransactionUnspentOutput": { + "title": "TransactionUnspentOutput", + "type": "object", + "properties": { + "input": { + "$ref": "cardano.json#/definitions/TransactionInput" + }, + "output": { + "$ref": "cardano.json#/definitions/TransactionOutput" + } + }, + "additionalProperties": false + }, + "TransactionMetadatum": { + "title": "TransactionMetadatum", + "oneOf": [ + { + "type": "object", + "properties": { + "tag": { + "enum": [ + "map" + ] + }, + "contents": { + "type": "array", + "items": { + "type": "object", + "properties": { + "key": { + "$ref": "cardano.json#/definitions/TransactionMetadatum" + }, + "value": { + "$ref": "cardano.json#/definitions/TransactionMetadatum" + } + } + } + } + } + }, + { + "type": "object", + "properties": { + "tag": { + "enum": [ + "list" + ] + }, + "contents": { + "type": "array", + "items": { + "$ref": "cardano.json#/definitions/TransactionMetadatum" + } + } + } + }, + { + "type": "object", + "properties": { + "tag": { + "enum": [ + "int" + ] + }, + "value": { + "$ref": "cardano.json#/definitions/Int" + } + } + }, + { + "type": "object", + "properties": { + "tag": { + "enum": [ + "bytes" + ] + }, + "value": { + "type": "array", + "items": { + "type": "string", + "contentEncoding": "hex", + "pattern": "^([0-9a-f][0-9a-f]){0,64}$" + } + } + } + }, + { + "type": "object", + "properties": { + "tag": { + "enum": [ + "string" + ] + }, + "value": { + "type": "string", + "maxLength": 64 + } + } + } + ] + }, "PlutusData": { "title": "PlutusData", "oneOf": [ From 9c48c2e91db509f9a5fe8235c62bc2d3ef033f81 Mon Sep 17 00:00:00 2001 From: Vladimir Kalnitsky Date: Wed, 31 Jan 2024 00:31:35 +0400 Subject: [PATCH 07/61] More types --- CIP-XXXX/schema.json | 288 +++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 276 insertions(+), 12 deletions(-) diff --git a/CIP-XXXX/schema.json b/CIP-XXXX/schema.json index 28c31b0f78..8506603d00 100644 --- a/CIP-XXXX/schema.json +++ b/CIP-XXXX/schema.json @@ -49,7 +49,7 @@ "title": "ByronAddress", "type": "string", "contentEncoding": "base58", - "pattern": "^[1-9A-HJ-NP-Za-km-z]*$" + "pattern": "^[1-9A-HJ-NP-Za-km-z]+$" }, "PointerAddress": { "title": "PointerAddress", @@ -71,7 +71,7 @@ }, "Address": { "title": "Address", - "oneOf": [ + "anyOf": [ { "$ref": "cardano.json#/definitions/RewardAddress" }, @@ -89,6 +89,50 @@ } ] }, + "Ed25519KeyHash": { + "title": "Ed25519KeyHash", + "type": "string", + "pattern": "^[0-9a-f]{56}$" + }, + "ScriptHash": { + "title": "ScriptHash", + "type": "string", + "pattern": "^[0-9a-f]{56}$" + }, + "Credential": { + "type": "object", + "discriminator": { + "propertyName": "tag" + }, + "oneOf": [ + { + "type": "object", + "properties": { + "tag": { + "enum": [ + "pubkey_hash" + ] + }, + "value": { + "$ref": "cardano.json#/definitions/Ed25519KeyHash" + } + } + }, + { + "type": "object", + "properties": { + "tag": { + "enum": [ + "script_hash" + ] + }, + "value": { + "$ref": "cardano.json#/definitions/ScriptHash" + } + } + } + ] + }, "MultiAsset": { "title": "MultiAsset", "description": "A mapping from policy IDs (script hashes) to mappings from asset names to amounts", @@ -144,6 +188,9 @@ }, "ScriptRef": { "title": "ScriptRef", + "discriminator": { + "propertyName": "tag" + }, "oneOf": [ { "title": "PlutusScript", @@ -194,6 +241,9 @@ "$ref": "cardano.json#/definitions/Value" }, "plutus_data": { + "discriminator": { + "propertyName": "tag" + }, "oneOf": [ { "type": "object", @@ -225,12 +275,12 @@ }, "script_ref": { "$ref": "cardano.json#/definitions/ScriptRef" - }, - "requiredProperties": [ - "address", - "amount" - ] - } + } + }, + "required": [ + "address", + "amount" + ] }, "TransactionUnspentOutput": { "title": "TransactionUnspentOutput", @@ -247,6 +297,9 @@ }, "TransactionMetadatum": { "title": "TransactionMetadatum", + "discriminator": { + "propertyName": "tag" + }, "oneOf": [ { "type": "object", @@ -337,13 +390,15 @@ }, "PlutusData": { "title": "PlutusData", + "discriminator": { + "propertyName": "tag" + }, "oneOf": [ { "title": "PlutusDataList", "type": "object", "properties": { "tag": { - "type": "string", "enum": [ "list" ] @@ -361,7 +416,6 @@ "type": "object", "properties": { "tag": { - "type": "string", "enum": [ "constr" ] @@ -382,7 +436,6 @@ "type": "object", "properties": { "tag": { - "type": "string", "enum": [ "map" ] @@ -423,7 +476,6 @@ "type": "object", "properties": { "tag": { - "type": "string", "enum": [ "bytes" ] @@ -436,6 +488,218 @@ } } ] + }, + "UnitInterval": { + "type": "object", + "properties": { + "numerator": { + "$ref": "cardano.json#/definitions/BigNum" + }, + "denominator": { + "$ref": "cardano.json#/definitions/BigNum" + } + }, + "additionalProperties": false + }, + "Ipv4": { + "title": "IPv4 Address", + "type": "string", + "pattern": "^((25[0-5]|(2[0-4]|1\\d|[1-9]|)\\d)\\.){3}(25[0-5]|(2[0-4]|1\\d|[1-9]|)\\d)$" + }, + "DNSName": { + "title": "DNSName", + "description": "", + "type": "string", + "maxLength": 64 + }, + "Relay": { + "discriminator": { + "propertyName": "tag" + }, + "oneOf": [ + { + "type": "object", + "title": "SingleHostAddr", + "properties": { + "tag": { + "enum": [ + "single_host_addr" + ] + }, + "port": { + "type": "integer", + "maxValue": 65535 + }, + "ipv4": { + "$ref": "cardano.json#/definitions/Ipv4" + }, + "ipv6": { + "$ref": "cardano.json#/definitions/Ipv6" + } + }, + "required": [ + "tag" + ], + "additionalProperties": false + }, + { + "type": "object", + "title": "SingleHostName", + "properties": { + "tag": { + "enum": [ + "single_host_name" + ] + }, + "port": { + "type": "integer", + "maxValue": 65535 + }, + "dnsName": { + "$ref": "cardano.json#/definitions/DNSName" + } + }, + "additionalProperties": false, + "required": [ + "tag" + ] + }, + { + "type": "object", + "title": "MultiHostName", + "properties": { + "tag": { + "enum": [ + "multi_host_name" + ] + }, + "dnsName": { + "$ref": "cardano.json#/definitions/DNSName" + } + }, + "additionalProperties": false, + "required": [ + "tag" + ] + } + ] + }, + "PoolParams": { + "type": "object", + "properties": { + "operator": { + "$ref": "cardano.json#/definitions/Ed25519KeyHash" + }, + "vrf_keyhash": { + "$ref": "cardano.json#/definitions/VRFKeyHash" + }, + "pledge": { + "$ref": "cardano.json#/definitions/BigNum" + }, + "cost": { + "$ref": "cardano.json#/definitions/BigNum" + }, + "margin": { + "$ref": "cardano.json#/definitions/UnitInterval" + }, + "reward_account": { + "$ref": "cardano.json#/definitions/RewardAddress" + }, + "pool_owners": { + "type": "array", + "items": { + "$ref": "cardano.json#/definitions/Ed25519KeyHash" + } + }, + "relays": { + "type": "array", + "items": { + "$ref": "cardano.json#/definitions/Relay" + } + }, + "pool_metadata": { + "type": "object", + "properties": { + "url": { + "$ref": "cardano.json#/definitions/URL" + }, + "pool_metadata_hash": { + "title": "Pool Metadata Hash", + "type": "string", + "pattern": "^[0-9a-f]{64}$" + } + }, + "additionalProperties": false + } + }, + "additionalProperties": false + }, + "Certificate": { + "title": "Certificate", + "discriminator": { + "propertyName": "tag" + }, + "oneOf": [ + { + "type": "object", + "properties": { + "tag": { + "type": "string", + "enum": [ + "stake_registration" + ] + }, + "credential": { + "$ref": "cardano.json#/definitions/Credential" + } + } + }, + { + "type": "object", + "properties": { + "tag": { + "type": "string", + "enum": [ + "stake_deregistration" + ] + }, + "credential": { + "$ref": "cardano.json#/definitions/Credential" + } + } + }, + { + "type": "object", + "properties": { + "tag": { + "type": "string", + "enum": [ + "stake_delegation" + ] + }, + "credential": { + "$ref": "cardano.json#/definitions/Credential" + }, + "pool_id": { + "$ref": "cardano.json#/definitions/PoolPubKeyHash" + } + } + }, + { + "type": "object", + "properties": { + "tag": { + "type": "string", + "enum": [ + "pool_registration" + ] + }, + "pool_params": { + "$ref": "cardano.json#/definitions/PoolParams" + } + } + } + ] } } } From 55348c6c1d25771c570258bedff28d94b3374a36 Mon Sep 17 00:00:00 2001 From: Vladimir Kalnitsky Date: Tue, 20 Feb 2024 01:08:00 +0400 Subject: [PATCH 08/61] Rename cardano.json to cardano-babbage.json --- CIP-XXXX/schema.json | 108 +++++++++++++++++++++---------------------- 1 file changed, 54 insertions(+), 54 deletions(-) diff --git a/CIP-XXXX/schema.json b/CIP-XXXX/schema.json index 8506603d00..ddffdc9469 100644 --- a/CIP-XXXX/schema.json +++ b/CIP-XXXX/schema.json @@ -1,6 +1,6 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "cardano.json", + "$id": "cardano-babbage.json", "title": "Cardano Domain Types", "definitions": { "BigInt": { @@ -73,19 +73,19 @@ "title": "Address", "anyOf": [ { - "$ref": "cardano.json#/definitions/RewardAddress" + "$ref": "cardano-babbage.json#/definitions/RewardAddress" }, { - "$ref": "cardano.json#/definitions/BaseAddress" + "$ref": "cardano-babbage.json#/definitions/BaseAddress" }, { - "$ref": "cardano.json#/definitions/PointerAddress" + "$ref": "cardano-babbage.json#/definitions/PointerAddress" }, { - "$ref": "cardano.json#/definitions/EnterpriseAddress" + "$ref": "cardano-babbage.json#/definitions/EnterpriseAddress" }, { - "$ref": "cardano.json#/definitions/ByronAddress" + "$ref": "cardano-babbage.json#/definitions/ByronAddress" } ] }, @@ -114,7 +114,7 @@ ] }, "value": { - "$ref": "cardano.json#/definitions/Ed25519KeyHash" + "$ref": "cardano-babbage.json#/definitions/Ed25519KeyHash" } } }, @@ -127,7 +127,7 @@ ] }, "value": { - "$ref": "cardano.json#/definitions/ScriptHash" + "$ref": "cardano-babbage.json#/definitions/ScriptHash" } } } @@ -142,7 +142,7 @@ "type": "object", "patternProperties": { "^([0-9a-f][0-9a-f]){0,32}$": { - "$ref": "cardano.json#/definitions/BigNum" + "$ref": "cardano-babbage.json#/definitions/BigNum" } }, "additionalProperties": false @@ -155,10 +155,10 @@ "type": "object", "properties": { "coin": { - "$ref": "cardano.json#/definitions/BigNum" + "$ref": "cardano-babbage.json#/definitions/BigNum" }, "multiasset": { - "$ref": "cardano.json#/definitions/MultiAsset" + "$ref": "cardano-babbage.json#/definitions/MultiAsset" } } }, @@ -171,10 +171,10 @@ "type": "object", "properties": { "hash": { - "$ref": "cardano.json#/definitions/TransactionHash" + "$ref": "cardano-babbage.json#/definitions/TransactionHash" }, "index": { - "$ref": "cardano.json#/definitions/UInt" + "$ref": "cardano-babbage.json#/definitions/UInt" } } }, @@ -203,7 +203,7 @@ ] }, "value": { - "$ref": "cardano.json#/definitions/PlutusScript" + "$ref": "cardano-babbage.json#/definitions/PlutusScript" } } }, @@ -218,7 +218,7 @@ ] }, "value": { - "$ref": "cardano.json#/definitions/NativeScript" + "$ref": "cardano-babbage.json#/definitions/NativeScript" } } } @@ -235,10 +235,10 @@ "type": "object", "properties": { "address": { - "$ref": "cardano.json#/definitions/Address" + "$ref": "cardano-babbage.json#/definitions/Address" }, "amount": { - "$ref": "cardano.json#/definitions/Value" + "$ref": "cardano-babbage.json#/definitions/Value" }, "plutus_data": { "discriminator": { @@ -254,7 +254,7 @@ ] }, "value": { - "$ref": "cardano.json#/definitions/PlutusData" + "$ref": "cardano-babbage.json#/definitions/PlutusData" } } }, @@ -267,14 +267,14 @@ ] }, "value": { - "$ref": "cardano.json#/definitions/DataHash" + "$ref": "cardano-babbage.json#/definitions/DataHash" } } } ] }, "script_ref": { - "$ref": "cardano.json#/definitions/ScriptRef" + "$ref": "cardano-babbage.json#/definitions/ScriptRef" } }, "required": [ @@ -287,10 +287,10 @@ "type": "object", "properties": { "input": { - "$ref": "cardano.json#/definitions/TransactionInput" + "$ref": "cardano-babbage.json#/definitions/TransactionInput" }, "output": { - "$ref": "cardano.json#/definitions/TransactionOutput" + "$ref": "cardano-babbage.json#/definitions/TransactionOutput" } }, "additionalProperties": false @@ -315,10 +315,10 @@ "type": "object", "properties": { "key": { - "$ref": "cardano.json#/definitions/TransactionMetadatum" + "$ref": "cardano-babbage.json#/definitions/TransactionMetadatum" }, "value": { - "$ref": "cardano.json#/definitions/TransactionMetadatum" + "$ref": "cardano-babbage.json#/definitions/TransactionMetadatum" } } } @@ -336,7 +336,7 @@ "contents": { "type": "array", "items": { - "$ref": "cardano.json#/definitions/TransactionMetadatum" + "$ref": "cardano-babbage.json#/definitions/TransactionMetadatum" } } } @@ -350,7 +350,7 @@ ] }, "value": { - "$ref": "cardano.json#/definitions/Int" + "$ref": "cardano-babbage.json#/definitions/Int" } } }, @@ -406,7 +406,7 @@ "contents": { "type": "array", "items": { - "$ref": "cardano.json#/definitions/PlutusData" + "$ref": "cardano-babbage.json#/definitions/PlutusData" } } } @@ -421,12 +421,12 @@ ] }, "alternative": { - "$ref": "cardano.json#/definitions/BigNum" + "$ref": "cardano-babbage.json#/definitions/BigNum" }, "data": { "type": "array", "items": { - "$ref": "cardano.json#/definitions/PlutusData" + "$ref": "cardano-babbage.json#/definitions/PlutusData" } } } @@ -446,10 +446,10 @@ "type": "object", "properties": { "key": { - "$ref": "cardano.json#/definitions/PlutusData" + "$ref": "cardano-babbage.json#/definitions/PlutusData" }, "value": { - "$ref": "cardano.json#/definitions/PlutusData" + "$ref": "cardano-babbage.json#/definitions/PlutusData" } } } @@ -467,7 +467,7 @@ ] }, "value": { - "$ref": "cardano.json#/definitions/BigInt" + "$ref": "cardano-babbage.json#/definitions/BigInt" } } }, @@ -493,10 +493,10 @@ "type": "object", "properties": { "numerator": { - "$ref": "cardano.json#/definitions/BigNum" + "$ref": "cardano-babbage.json#/definitions/BigNum" }, "denominator": { - "$ref": "cardano.json#/definitions/BigNum" + "$ref": "cardano-babbage.json#/definitions/BigNum" } }, "additionalProperties": false @@ -531,10 +531,10 @@ "maxValue": 65535 }, "ipv4": { - "$ref": "cardano.json#/definitions/Ipv4" + "$ref": "cardano-babbage.json#/definitions/Ipv4" }, "ipv6": { - "$ref": "cardano.json#/definitions/Ipv6" + "$ref": "cardano-babbage.json#/definitions/Ipv6" } }, "required": [ @@ -556,7 +556,7 @@ "maxValue": 65535 }, "dnsName": { - "$ref": "cardano.json#/definitions/DNSName" + "$ref": "cardano-babbage.json#/definitions/DNSName" } }, "additionalProperties": false, @@ -574,7 +574,7 @@ ] }, "dnsName": { - "$ref": "cardano.json#/definitions/DNSName" + "$ref": "cardano-babbage.json#/definitions/DNSName" } }, "additionalProperties": false, @@ -588,40 +588,40 @@ "type": "object", "properties": { "operator": { - "$ref": "cardano.json#/definitions/Ed25519KeyHash" + "$ref": "cardano-babbage.json#/definitions/Ed25519KeyHash" }, "vrf_keyhash": { - "$ref": "cardano.json#/definitions/VRFKeyHash" + "$ref": "cardano-babbage.json#/definitions/VRFKeyHash" }, "pledge": { - "$ref": "cardano.json#/definitions/BigNum" + "$ref": "cardano-babbage.json#/definitions/BigNum" }, "cost": { - "$ref": "cardano.json#/definitions/BigNum" + "$ref": "cardano-babbage.json#/definitions/BigNum" }, "margin": { - "$ref": "cardano.json#/definitions/UnitInterval" + "$ref": "cardano-babbage.json#/definitions/UnitInterval" }, "reward_account": { - "$ref": "cardano.json#/definitions/RewardAddress" + "$ref": "cardano-babbage.json#/definitions/RewardAddress" }, "pool_owners": { "type": "array", "items": { - "$ref": "cardano.json#/definitions/Ed25519KeyHash" + "$ref": "cardano-babbage.json#/definitions/Ed25519KeyHash" } }, "relays": { "type": "array", "items": { - "$ref": "cardano.json#/definitions/Relay" + "$ref": "cardano-babbage.json#/definitions/Relay" } }, "pool_metadata": { "type": "object", "properties": { "url": { - "$ref": "cardano.json#/definitions/URL" + "$ref": "cardano-babbage.json#/definitions/URL" }, "pool_metadata_hash": { "title": "Pool Metadata Hash", @@ -650,7 +650,7 @@ ] }, "credential": { - "$ref": "cardano.json#/definitions/Credential" + "$ref": "cardano-babbage.json#/definitions/Credential" } } }, @@ -664,7 +664,7 @@ ] }, "credential": { - "$ref": "cardano.json#/definitions/Credential" + "$ref": "cardano-babbage.json#/definitions/Credential" } } }, @@ -677,11 +677,11 @@ "stake_delegation" ] }, - "credential": { - "$ref": "cardano.json#/definitions/Credential" + "stake_credential": { + "$ref": "cardano-babbage.json#/definitions/Credential" }, - "pool_id": { - "$ref": "cardano.json#/definitions/PoolPubKeyHash" + "pool_keyhash": { + "$ref": "cardano-babbage.json#/definitions/Ed25519KeyHash" } } }, @@ -695,7 +695,7 @@ ] }, "pool_params": { - "$ref": "cardano.json#/definitions/PoolParams" + "$ref": "cardano-babbage.json#/definitions/PoolParams" } } } From 6da3763c4d69722316e0b7ebbaf9c329e8e19cd0 Mon Sep 17 00:00:00 2001 From: Vladimir Kalnitsky Date: Tue, 20 Feb 2024 04:39:50 +0400 Subject: [PATCH 09/61] Add NativeScript, Update, TransactionBody --- CIP-XXXX/schema.json | 527 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 526 insertions(+), 1 deletion(-) diff --git a/CIP-XXXX/schema.json b/CIP-XXXX/schema.json index ddffdc9469..6e64e59505 100644 --- a/CIP-XXXX/schema.json +++ b/CIP-XXXX/schema.json @@ -184,7 +184,120 @@ "pattern": "^([0-9a-f][0-9a-f])+$" }, "NativeScript": { - "title": "TODO align with cardano-cli" + "title": "NativeScript", + "discriminator": { + "propertyName": "tag" + }, + "oneOf": [ + { + "title": "ScriptPubkey", + "type": "object", + "properties": { + "tag": { + "enum": [ + "pubkey" + ] + }, + "pubkey": { + "$ref": "cardano-babbage.json#/definitions/Ed25519KeyHash" + } + }, + "additionalProperties": false, + "requiredProperties": ["tag", "pubkey"] + }, + { + "title": "ScriptAll", + "type": "object", + "properties": { + "tag": { + "enum": [ + "all" + ] + }, + "scripts": { + "type": "array", + "items": { + "$ref": "cardano-babbage.json#/definitions/NativeScript" + } + } + }, + "additionalProperties": false, + "requiredProperties": ["tag", "scripts"] + }, + { + "title": "ScriptAny", + "type": "object", + "properties": { + "tag": { + "enum": [ + "any" + ] + }, + "scripts": { + "type": "array", + "items": { + "$ref": "cardano-babbage.json#/definitions/NativeScript" + } + } + }, + "additionalProperties": false, + "requiredProperties": ["tag", "scripts"] + }, + { + "title": "ScriptNOfK", + "type": "object", + "properties": { + "tag": { + "enum": [ + "n_of_k" + ] + }, + "scripts": { + "type": "array", + "items": { + "$ref": "cardano-babbage.json#/definitions/NativeScript" + } + }, + "n": { + "$ref": "cardano-babbage.json#/definitions/UInt" + } + }, + "additionalProperties": false, + "requiredProperties": [ "tag", "scripts", "n" ] + }, + { + "title": "TimelockStart", + "type": "object", + "properties": { + "tag": { + "enum": [ + "timelock_start" + ] + }, + "slot": { + "$ref": "cardano-babbage.json#/definitions/BigNum" + } + }, + "additionalProperties": false, + "requiredProperties": [ "tag", "slot" ] + }, + { + "title": "TimelockExpiry", + "type": "object", + "properties": { + "tag": { + "enum": [ + "timelock_expiry" + ] + }, + "slot": { + "$ref": "cardano-babbage.json#/definitions/BigNum" + } + }, + "additionalProperties": false, + "requiredProperties": [ "tag", "slot" ] + } + ] }, "ScriptRef": { "title": "ScriptRef", @@ -388,6 +501,321 @@ } ] }, + "PlutusV1CostModel": { + "title": "CostModel", + "type": "array", + "items": { + "$ref": "cardano-babbage.json#/definitions/Int" + }, + "maxLength": 166, + "minLength": 166 + }, + "PlutusV2CostModel": { + "title": "CostModel", + "type": "array", + "items": { + "$ref": "cardano-babbage.json#/definitions/Int" + }, + "maxLength": 175, + "minLength": 175 + }, + "CostModels": { + "title": "CostModels", + "type": "object", + "properties": { + "PlutusV1": { + "$ref": "cardano-babbage.json#/definitions/PlutusV1CostModel" + }, + "PlutusV2": { + "$ref": "cardano-babbage.json#/definitions/PlutusV2CostModel" + } + } + }, + "ExUnitPrices": { + "title": "ExUnitPrices", + "type": "object", + "properties": { + "mem_price": { + "$ref": "cardano-babbage.json#/definitions/UnitInterval" + }, + "step_price": { + "$ref": "cardano-babbage.json#/definitions/UnitInterval" + } + } + }, + "Nonce": { + "title": "Nonce", + "oneOf": [ + { + "title": "Identity Nonce", + "type": "string", + "enum": [ + "" + ] + }, + { + "title": "Nonce from hash", + "type": "string", + "pattern": "^[0-9a-f]{64}$" + } + ] + }, + "ExUnits": { + "title": "ExUnits", + "type": "object", + "properties": { + "mem": { + "$ref": "cardano-babbage.json#/definitions/BigNum" + }, + "steps": { + "$ref": "cardano-babbage.json#/definitions/BigNum" + } + }, + "additionalProperties": false + }, + "ProtocolVersion": { + "title": "ProtocolVersion", + "type": "object", + "properties": { + "major": { + "$ref": "cardano-babbage.json#/definitions/UInt" + }, + "minor": { + "$ref": "cardano-babbage.json#/definitions/UInt" + } + }, + "additionalProperties": false + }, + "ProtocolParamUpdate": { + "type": "object", + "title": "ProtocolParamUpdate", + "properties": { + "ada_per_utxo_byte": { + "$ref": "cardano-babbage.json#/definitions/BigNum" + }, + "collateral_percentage": { + "$ref": "cardano-babbage.json#/definitions/UInt" + }, + "cost_models": { + "$ref": "cardano-babbage.json#/definitions/CostModels" + }, + "d": { + "$ref": "cardano-babbage.json#/definitions/UnitInterval" + }, + "execution_costs": { + "$ref": "cardano-babbage.json#/definitions/ExUnitPrices" + }, + "expansion_rate": { + "$ref": "cardano-babbage.json#/definitions/UnitInterval" + }, + "extra_entropy": { + "$ref": "cardano-babbage.json#/definitions/Nonce" + }, + "key_deposit": { + "$ref": "cardano-babbage.json#/definitions/BigNum" + }, + "max_block_body_size": { + "$ref": "cardano-babbage.json#/definitions/UInt" + }, + "max_block_ex_units": { + "$ref": "cardano-babbage.json#/definitions/ExUnits" + }, + "max_block_header_size": { + "$ref": "cardano-babbage.json#/definitions/UInt" + }, + "max_collateral_inputs": { + "$ref": "cardano-babbage.json#/definitions/UInt" + }, + "max_epoch": { + "$ref": "cardano-babbage.json#/definitions/UInt" + }, + "max_tx_ex_units": { + "$ref": "cardano-babbage.json#/definitions/ExUnits" + }, + "max_tx_size": { + "$ref": "cardano-babbage.json#/definitions/UInt" + }, + "max_value_size": { + "$ref": "cardano-babbage.json#/definitions/UInt" + }, + "min_pool_cost": { + "$ref": "cardano-babbage.json#/definitions/BigNum" + }, + "minfee_a": { + "$ref": "cardano-babbage.json#/definitions/BigNum" + }, + "minfee_b": { + "$ref": "cardano-babbage.json#/definitions/BigNum" + }, + "n_opt": { + "$ref": "cardano-babbage.json#/definitions/Int" + }, + "pool_deposit": { + "$ref": "cardano-babbage.json#/definitions/BigNum" + }, + "pool_pledge_influence": { + "$ref": "cardano-babbage.json#/definitions/UnitInterval" + }, + "protocol_version": { + "$ref": "cardano-babbage.json#/definitions/ProtocolVersion" + }, + "treasury_growth_rate": { + "$ref": "cardano-babbage.json#/definitions/UnitInterval" + } + }, + "additionalProperties": false + }, + "Update": { + "type": "object", + "title": "Update", + "properties": { + "epoch": { + "$ref": "cardano-babbage.json#/definitions/UInt" + }, + "proposed_protocol_parameter_updates": { + "type": "object", + "title": "ProposedProtocolParameterUpdates", + "description": "A mapping from GenesisHash to ProtocolParamUpdate", + "patternProperties": { + "^[0-9a-f]{56}$": { + "$ref": "cardano-babbage.json#/definitions/ProtocolParamUpdate" + } + } + } + }, + "requiredProperties": [ + "epoch", + "proposed_protocol_parameter_updates" + ], + "additionalProperties": false + }, + "ScriptDataHash": { + "title": "ScriptDataHash", + "type": "string", + "pattern": "^[0-9a-f]{64}$" + }, + "AuxiliaryDataHash": { + "title": "Auxiliary Data Hash", + "type": "string", + "pattern": "^[0-9a-f]{64}$" + }, + "TransactionBody": { + "type": "object", + "properties": { + "auxiliary_data_hash": { + "$ref": "cardano-babbage.json#/definitions/AuxiliaryDataHash" + }, + "inputs": { + "type": "array", + "items": { + "$ref": "cardano-babbage.json#/definitions/TransactionInput" + } + }, + "outputs": { + "type": "array", + "items": { + "$ref": "cardano-babbage.json#/definitions/TransactionOutput" + } + }, + "fee": { + "$ref": "cardano-babbage.json#/definitions/BigNum" + }, + "certs": { + "type": "array", + "items": { + "$ref": "cardano-babbage.json#/definitions/Certificate" + } + }, + "collateral": { + "title": "Collateral Inputs", + "type": "array", + "items": { + "$ref": "cardano-babbage.json#/definitions/TransactionInput" + } + }, + "collateral_return": { + "allOf": [ + { + "$ref": "cardano-babbage.json#/definitions/TransactionOutput" + }, + { + "title": "Collateral Return", + "description": "Collateral return, introduced in CIP-40" + } + ] + }, + "mint": { + "$ref": "cardano-babbage.json#/definitions/Mint" + }, + "network_id": { + "$ref": "cardano-babbage.json#/definitions/NetworkId" + }, + "reference_inputs": { + "type": "array", + "items": { + "$ref": "cardano-babbage.json#/definitions/TransactionInput" + } + }, + "required_signers": { + "title": "Required signers", + "type": "array", + "items": { + "$ref": "cardano-babbage.json#/definitions/Ed25519KeyHash" + } + }, + "script_data_hash": { + "$ref": "cardano-babbage.json#/definitions/ScriptDataHash" + }, + "total_collateral": { + "allOf": [ + { + "title": "Total collateral value" + }, + { + "$ref": "cardano-babbage.json#/definitions/BigNum" + } + ] + }, + "ttl": { + "$ref": "cardano-babbage.json#/definitions/BigNum" + }, + "update": { + "$ref": "cardano-babbage.json#/definitions/Update" + }, + "validity_start_interval": { + "$ref": "cardano-babbage.json#/definitions/BigNum" + }, + "withdrawals": { + "type": "array", + "items": { + "type": "object", + "properties": { + "key": { + "$ref": "cardano-babbage.json#/definitions/RewardAddress" + }, + "value": { + "$ref": "cardano-babbage.json#/definitions/BigNum" + } + }, + "additionalProperties": false + } + } + }, + "requiredProperties": [ + "inputs", + "outputs", + "fee" + ], + "additionalProperties": false + }, + "NetworkId": { + "title": "NetworkId", + "type": "string", + "enum": [ + "Testnet", + "Mainnet" + ] + }, "PlutusData": { "title": "PlutusData", "discriminator": { @@ -512,6 +940,12 @@ "type": "string", "maxLength": 64 }, + "Ipv6": { + "title": "Ipv6", + "description": "IPv6 address in fully-expanded form", + "type": "string", + "pattern": "^([0-9a-f]{4}:){7}:[0-9a-f]{4}$" + }, "Relay": { "discriminator": { "propertyName": "tag" @@ -584,6 +1018,19 @@ } ] }, + "VRFKeyHash": { + "type": "string", + "title": "VRFKeyHash", + "description": "VRF verification key hash. blake2b_256 digest of a VRF verification key, encoded as bech32", + "type": "string", + "pattern": "^vrf_vkh[02-9ac-hj-np-z]*" + }, + "URL": { + "title": "URL", + "description": "UTF-8 URL string. Maximum size is 64 bytes, but there is no way to express byte length limit in a json-schema (maxLength limits the number of characters)", + "type": "string", + "maxLength": 64 + }, "PoolParams": { "type": "object", "properties": { @@ -634,6 +1081,16 @@ }, "additionalProperties": false }, + "GenesisHash": { + "title": "GenesisHash", + "type": "string", + "pattern": "^[0-9a-f]{56}$" + }, + "GenesisDelegateHash": { + "title": "GenesisDelegateHash", + "type": "string", + "pattern": "^[0-9a-f]{56}$" + }, "Certificate": { "title": "Certificate", "discriminator": { @@ -642,6 +1099,7 @@ "oneOf": [ { "type": "object", + "title": "Stake Registration Certificate", "properties": { "tag": { "type": "string", @@ -656,6 +1114,7 @@ }, { "type": "object", + "title": "Stake Deregistration Certificate", "properties": { "tag": { "type": "string", @@ -670,6 +1129,7 @@ }, { "type": "object", + "title": "Stake Delegation Certificate", "properties": { "tag": { "type": "string", @@ -687,6 +1147,7 @@ }, { "type": "object", + "title": "Pool Registration Certificate", "properties": { "tag": { "type": "string", @@ -698,8 +1159,72 @@ "$ref": "cardano-babbage.json#/definitions/PoolParams" } } + }, + { + "type": "object", + "title": "Pool Retirement Certificate", + "properties": { + "tag": { + "type": "string", + "enum": [ + "pool_retirement" + ] + }, + "pool_keyhash": { + "$ref": "cardano-babbage.json#/definitions/Ed25519KeyHash" + }, + "epoch": { + "$ref": "cardano-babbage.json#/definitions/UInt" + } + } + }, + { + "type": "object", + "title": "Genesis Key Delegation Certificate", + "properties": { + "tag": { + "type": "string", + "enum": [ + "genesis_key_delegation" + ] + }, + "genesis_hash": { + "$ref": "cardano-babbage.json#/definitions/GenesisHash" + }, + "genesis_delegate_hash": { + "$ref": "cardano-babbage.json#/definitions/GenesisDelegateHash" + }, + "vrf_keyhash": { + "$ref": "cardano-babbage.json#/definitions/VRFKeyHash" + } + } } ] + }, + "Language": { + "title": "Language", + "type": "string", + "enum": [ + "PlutusV1", + "PlutusV2" + ] + }, + "Mint": { + "title": "Mint", + "description": "Minting or burning of assets. A mapping from policy IDs (script hashes) to mappings from asset names to amounts (that can be negative)", + "type": "object", + "patternProperties": { + "^[0-9a-f]{56}$": { + "type": "object", + "patternProperties": { + "^([0-9a-f][0-9a-f]){0,32}$": { + "$ref": "cardano-babbage.json#/definitions/Int" + } + }, + "additionalProperties": false + } + }, + "additionalProperties": false } } } From a72e8220226df8cafceaae25edcb185f0c57c10f Mon Sep 17 00:00:00 2001 From: Vladimir Kalnitsky Date: Wed, 21 Feb 2024 20:34:42 +0400 Subject: [PATCH 10/61] - Fix: requiredProperties -> required - New types: TransactionWitnessSet, MIR, BootstrapWitness, etc --- CIP-XXXX/schema.json | 347 +++++++++++++++++++++++++++++++++++++------ 1 file changed, 301 insertions(+), 46 deletions(-) diff --git a/CIP-XXXX/schema.json b/CIP-XXXX/schema.json index 6e64e59505..de62ec39e5 100644 --- a/CIP-XXXX/schema.json +++ b/CIP-XXXX/schema.json @@ -116,7 +116,9 @@ "value": { "$ref": "cardano-babbage.json#/definitions/Ed25519KeyHash" } - } + }, + "required": ["tag", "value"], + "additionalProperties": false }, { "type": "object", @@ -129,7 +131,9 @@ "value": { "$ref": "cardano-babbage.json#/definitions/ScriptHash" } - } + }, + "required": ["tag", "value"], + "additionalProperties": false } ] }, @@ -160,7 +164,9 @@ "multiasset": { "$ref": "cardano-babbage.json#/definitions/MultiAsset" } - } + }, + "required": ["coin", "multiasset"], + "additionalProperties": false }, "TransactionHash": { "title": "TransactionHash", @@ -170,13 +176,15 @@ "TransactionInput": { "type": "object", "properties": { - "hash": { + "transaction_id": { "$ref": "cardano-babbage.json#/definitions/TransactionHash" }, "index": { "$ref": "cardano-babbage.json#/definitions/UInt" } - } + }, + "required": ["transaction_id", "index"], + "additionalProperties": false }, "PlutusScript": { "type": "string", @@ -203,7 +211,7 @@ } }, "additionalProperties": false, - "requiredProperties": ["tag", "pubkey"] + "required": ["tag", "pubkey"] }, { "title": "ScriptAll", @@ -222,7 +230,7 @@ } }, "additionalProperties": false, - "requiredProperties": ["tag", "scripts"] + "required": ["tag", "scripts"] }, { "title": "ScriptAny", @@ -241,7 +249,7 @@ } }, "additionalProperties": false, - "requiredProperties": ["tag", "scripts"] + "required": ["tag", "scripts"] }, { "title": "ScriptNOfK", @@ -263,7 +271,7 @@ } }, "additionalProperties": false, - "requiredProperties": [ "tag", "scripts", "n" ] + "required": [ "tag", "scripts", "n" ] }, { "title": "TimelockStart", @@ -279,7 +287,7 @@ } }, "additionalProperties": false, - "requiredProperties": [ "tag", "slot" ] + "required": [ "tag", "slot" ] }, { "title": "TimelockExpiry", @@ -295,7 +303,7 @@ } }, "additionalProperties": false, - "requiredProperties": [ "tag", "slot" ] + "required": [ "tag", "slot" ] } ] }, @@ -318,7 +326,9 @@ "value": { "$ref": "cardano-babbage.json#/definitions/PlutusScript" } - } + }, + "required": ["tag", "value"], + "additionalProperties": false }, { "title": "NativeScript", @@ -333,7 +343,9 @@ "value": { "$ref": "cardano-babbage.json#/definitions/NativeScript" } - } + }, + "required": ["tag", "value"], + "additionalProperties": false } ] }, @@ -406,6 +418,7 @@ "$ref": "cardano-babbage.json#/definitions/TransactionOutput" } }, + "required": ["input", "output"], "additionalProperties": false }, "TransactionMetadatum": { @@ -436,7 +449,9 @@ } } } - } + }, + "required": [ "tag", "contents" ], + "additionalProperties": false }, { "type": "object", @@ -452,7 +467,9 @@ "$ref": "cardano-babbage.json#/definitions/TransactionMetadatum" } } - } + }, + "required": [ "tag", "contents" ], + "additionalProperties": false }, { "type": "object", @@ -465,7 +482,9 @@ "value": { "$ref": "cardano-babbage.json#/definitions/Int" } - } + }, + "required": [ "tag", "value" ], + "additionalProperties": false }, { "type": "object", @@ -483,9 +502,13 @@ "pattern": "^([0-9a-f][0-9a-f]){0,64}$" } } - } + }, + "required": [ "tag", "value" ], + "additionalProperties": false }, { + "title": "Metadata String", + "description": "UTF-8 string. Maximum size is 64 bytes, but there is no way to express byte length limit in a json-schema (maxLength limits the number of characters)", "type": "object", "properties": { "tag": { @@ -497,7 +520,9 @@ "type": "string", "maxLength": 64 } - } + }, + "required": [ "tag", "value" ], + "additionalProperties": false } ] }, @@ -529,7 +554,9 @@ "PlutusV2": { "$ref": "cardano-babbage.json#/definitions/PlutusV2CostModel" } - } + }, + "required": [], + "additionalProperties": false }, "ExUnitPrices": { "title": "ExUnitPrices", @@ -541,7 +568,9 @@ "step_price": { "$ref": "cardano-babbage.json#/definitions/UnitInterval" } - } + }, + "additionalProperties": false, + "required": [ "mem_price", "step_price" ] }, "Nonce": { "title": "Nonce", @@ -571,6 +600,7 @@ "$ref": "cardano-babbage.json#/definitions/BigNum" } }, + "required": [ "mem", "steps" ], "additionalProperties": false }, "ProtocolVersion": { @@ -584,6 +614,7 @@ "$ref": "cardano-babbage.json#/definitions/UInt" } }, + "required": [ "major", "minor" ], "additionalProperties": false }, "ProtocolParamUpdate": { @@ -663,7 +694,8 @@ "$ref": "cardano-babbage.json#/definitions/UnitInterval" } }, - "additionalProperties": false + "additionalProperties": false, + "required": [] }, "Update": { "type": "object", @@ -683,7 +715,7 @@ } } }, - "requiredProperties": [ + "required": [ "epoch", "proposed_protocol_parameter_updates" ], @@ -767,14 +799,7 @@ "$ref": "cardano-babbage.json#/definitions/ScriptDataHash" }, "total_collateral": { - "allOf": [ - { - "title": "Total collateral value" - }, - { - "$ref": "cardano-babbage.json#/definitions/BigNum" - } - ] + "$ref": "cardano-babbage.json#/definitions/BigNum" }, "ttl": { "$ref": "cardano-babbage.json#/definitions/BigNum" @@ -801,7 +826,7 @@ } } }, - "requiredProperties": [ + "required": [ "inputs", "outputs", "fee" @@ -812,8 +837,8 @@ "title": "NetworkId", "type": "string", "enum": [ - "Testnet", - "Mainnet" + "testnet", + "mainnet" ] }, "PlutusData": { @@ -1021,7 +1046,7 @@ "VRFKeyHash": { "type": "string", "title": "VRFKeyHash", - "description": "VRF verification key hash. blake2b_256 digest of a VRF verification key, encoded as bech32", + "description": "blake2b_256 digest of a VRF verification key, encoded as bech32", "type": "string", "pattern": "^vrf_vkh[02-9ac-hj-np-z]*" }, @@ -1091,6 +1116,83 @@ "type": "string", "pattern": "^[0-9a-f]{56}$" }, + "MIRPot": { + "title": "MIRPot", + "enum": [ + "reserves", + "treasury" + ] + }, + "MoveInstantaneousRewards": { + "title": "MoveInstantaneousRewards", + "discriminator": { + "propertyName": "tag" + }, + "oneOf": [ + { + "type": "object", + "title": "Move Instantaneous Rewards to stake credentials", + "properties": { + "tag": { + "enum": [ + "to_stake_creds" + ] + }, + "pot": { + "$ref": "cardano-babbage.json#/definitions/MIRPot" + }, + "rewards": { + "title": "MIRToStakeCredentials", + "description": "Distribution of rewards", + "type": "array", + "items": { + "type": "object", + "properties": { + "key": { + "$ref": "cardano-babbage.json#/definitions/Credential" + }, + "value": { + "$ref": "cardano-babbage.json#/definitions/Int" + } + }, + "required": [ + "key", + "value" + ], + "additionalProperties": false + } + } + }, + "additionalProperties": false, + "required": [ + "pot", + "rewards" + ] + }, + { + "type": "object", + "title": "Move Instantaneous Rewards to other Pot (reserves or treasury)", + "properties": { + "tag": { + "enum": [ + "to_other_pot" + ] + }, + "pot": { + "$ref": "cardano-babbage.json#/definitions/MIRPot" + }, + "amount": { + "$ref": "cardano-babbage.json#/definitions/BigNum" + } + }, + "additionalProperties": false, + "required": [ + "pot", + "amount" + ] + } + ] + }, "Certificate": { "title": "Certificate", "discriminator": { @@ -1102,7 +1204,6 @@ "title": "Stake Registration Certificate", "properties": { "tag": { - "type": "string", "enum": [ "stake_registration" ] @@ -1110,14 +1211,15 @@ "credential": { "$ref": "cardano-babbage.json#/definitions/Credential" } - } + }, + "required": ["tag", "credential"], + "additionalProperties": false }, { "type": "object", "title": "Stake Deregistration Certificate", "properties": { "tag": { - "type": "string", "enum": [ "stake_deregistration" ] @@ -1125,14 +1227,15 @@ "credential": { "$ref": "cardano-babbage.json#/definitions/Credential" } - } + }, + "required": ["tag", "credential"], + "additionalProperties": false }, { "type": "object", "title": "Stake Delegation Certificate", "properties": { "tag": { - "type": "string", "enum": [ "stake_delegation" ] @@ -1143,14 +1246,15 @@ "pool_keyhash": { "$ref": "cardano-babbage.json#/definitions/Ed25519KeyHash" } - } + }, + "required": ["tag", "stake_credential", "pool_keyhash"], + "additionalProperties": false }, { "type": "object", "title": "Pool Registration Certificate", "properties": { "tag": { - "type": "string", "enum": [ "pool_registration" ] @@ -1158,7 +1262,9 @@ "pool_params": { "$ref": "cardano-babbage.json#/definitions/PoolParams" } - } + }, + "required": ["tag", "pool_params"], + "additionalProperties": false }, { "type": "object", @@ -1176,7 +1282,9 @@ "epoch": { "$ref": "cardano-babbage.json#/definitions/UInt" } - } + }, + "required": ["tag", "pool_keyhash", "epoch"], + "additionalProperties": false }, { "type": "object", @@ -1197,7 +1305,25 @@ "vrf_keyhash": { "$ref": "cardano-babbage.json#/definitions/VRFKeyHash" } - } + }, + "required": ["tag", "genesis_hash", "genesis_delegate_hash", "vrf_keyhash"], + "additionalProperties": false + }, + { + "type": "object", + "title": "Move Instantaneous Rewards Certificate", + "properties": { + "tag": { + "enum": [ + "move_instantaneous_rewards" + ] + }, + "move_instantaneous_rewards": { + "$ref": "cardano-babbage.json#/definitions/MoveInstantaneousRewards" + } + }, + "required": ["tag", "move_instantaneous_rewards"], + "additionalProperties": false } ] }, @@ -1205,8 +1331,8 @@ "title": "Language", "type": "string", "enum": [ - "PlutusV1", - "PlutusV2" + "plutus_v1", + "plutus_v2" ] }, "Mint": { @@ -1225,6 +1351,135 @@ } }, "additionalProperties": false + }, + "Ed25519Signature": { + "title": "Ed25519Signature", + "type": "string", + "pattern": "^([0-9a-f][0-9a-f]){64}$" + }, + "Ed25519PublicKey": { + "title": "Ed25519PublicKey", + "type": "string", + "pattern": "^([0-9a-f][0-9a-f]){32}$" + }, + "BootstrapWitness": { + "type": "object", + "properties": { + "attributes": { + "type": "string", + "pattern": "^([0-9a-f][0-9a-f])*$" + }, + "chain_code": { + "type": "string", + "pattern": "^([0-9a-f][0-9a-f])*$" + }, + "signature": { + "$ref": "cardano-babbage.json#/definitions/Ed25519Signature" + }, + "vkey": { + "$ref": "cardano-babbage.json#/definitions/Ed25519PublicKey" + } + }, + "required": [ + "attributes", + "chain_code", + "signature", + "vkey" + ], + "additionalProperties": false + }, + "RedeemerTag": { + "title": "RedeemerTag", + "type": "string", + "enum": [ + "spend", + "mint", + "cert", + "reward" + ] + }, + "Redeemer": { + "title": "Redeemer", + "type": "object", + "properties": { + "data": { + "$ref": "cardano-babbage.json#/definitions/PlutusData" + }, + "tag": { + "$ref": "cardano-babbage.json#/definitions/RedeemerTag" + }, + "index": { + "$ref": "cardano-babbage.json#/definitions/BigNum" + }, + "ex_units": { + "$ref": "cardano-babbage.json#/definitions/ExUnits" + } + }, + "required": ["data", "tag", "index", "ex_units"], + "additionalProperties": false + }, + "Vkeywitness": { + "title": "Vkeywitness", + "type": "object", + "properties": { + "vkey": { + "$ref": "cardano-babbage.json#/definitions/Ed25519PublicKey" + }, + "signature": { + "$ref": "cardano-babbage.json#/definitions/Ed25519Signature" + } + }, + "required": ["vkey", "signature"], + "additionalProperties": false + }, + "TransactionWitnessSet": { + "title": "TransactionWitnessSet", + "type": "object", + "properties": { + "bootstraps": { + "title": "BootstrapWitnesses", + "type": "array", + "items": { + "$ref": "cardano-babbage.json#/definitions/BootstrapWitness" + } + }, + "native_scripts": { + "title": "NativeScripts", + "type": "array", + "items": { + "$ref": "cardano-babbage.json#/definitions/NativeScript" + } + }, + "plutus_data": { + "type": "array", + "title": "PlutusList", + "items": { + "$ref": "cardano-babbage.json#/definitions/PlutusData" + } + }, + "plutus_scripts": { + "type": "array", + "title": "PlutusScripts", + "items": { + "$ref": "cardano-babbage.json#/definitions/PlutusScript" + } + }, + "redeemers": { + "type": "array", + "title": "Redeemers", + "items": { + "$ref": "cardano-babbage.json#/definitions/Redeemer" + } + }, + "vkeywitnesses": { + "type": "array", + "title": "VkeyWitnesses", + "items": { + "$ref": "cardano-babbage.json#/definitions/Vkeywitness" + } + } + }, + "required": [] } } } From 088b881ca386ce7cb25a430abca5cfed6c9d938c Mon Sep 17 00:00:00 2001 From: Vladimir Kalnitsky Date: Wed, 21 Feb 2024 21:16:38 +0400 Subject: [PATCH 11/61] Use `format` instead of `contentEncoding` --- CIP-XXXX/schema.json | 36 +++++++++++++++++++++++++----------- 1 file changed, 25 insertions(+), 11 deletions(-) diff --git a/CIP-XXXX/schema.json b/CIP-XXXX/schema.json index de62ec39e5..0bf6748449 100644 --- a/CIP-XXXX/schema.json +++ b/CIP-XXXX/schema.json @@ -18,7 +18,7 @@ "title": "ByteString", "description": "Arbitrary-length byte array", "type": "string", - "contentEncoding": "hex", + "format": "hex", "pattern": "^([0-9a-f][0-9a-f])+$" }, "BigNum": { @@ -42,31 +42,31 @@ "RewardAddress": { "title": "RewardAddress", "type": "string", - "contentEncoding": "bech32", + "format": "bech32", "pattern": "^(addr1|addr_test1)[02-9ac-hj-np-z]*$" }, "ByronAddress": { "title": "ByronAddress", "type": "string", - "contentEncoding": "base58", + "format": "base58", "pattern": "^[1-9A-HJ-NP-Za-km-z]+$" }, "PointerAddress": { "title": "PointerAddress", "type": "string", - "contentEncoding": "bech32", + "format": "bech32", "pattern": "^(addr1|addr_test1)[02-9ac-hj-np-z]*$" }, "EnterpriseAddress": { "title": "EnterpriseAddress", "type": "string", - "contentEncoding": "bech32", + "format": "bech32", "pattern": "^(addr1|addr_test1)[02-9ac-hj-np-z]*$" }, "BaseAddress": { "title": "BaseAddress", "type": "string", - "contentEncoding": "bech32", + "format": "bech32", "pattern": "^(addr1|addr_test1)[02-9ac-hj-np-z]*$" }, "Address": { @@ -92,11 +92,13 @@ "Ed25519KeyHash": { "title": "Ed25519KeyHash", "type": "string", + "format": "hex", "pattern": "^[0-9a-f]{56}$" }, "ScriptHash": { "title": "ScriptHash", "type": "string", + "format": "hex", "pattern": "^[0-9a-f]{56}$" }, "Credential": { @@ -171,6 +173,7 @@ "TransactionHash": { "title": "TransactionHash", "type": "string", + "format": "hex", "pattern": "^[0-9a-f]{64}$" }, "TransactionInput": { @@ -188,7 +191,7 @@ }, "PlutusScript": { "type": "string", - "contentEncoding": "hex", + "format": "hex", "pattern": "^([0-9a-f][0-9a-f])+$" }, "NativeScript": { @@ -352,7 +355,7 @@ "DataHash": { "title": "DataHash", "type": "string", - "contentEncoding": "hex", + "format": "hex", "pattern": "^([0-9a-f][0-9a-f]){32}$" }, "TransactionOutput": { @@ -498,7 +501,7 @@ "type": "array", "items": { "type": "string", - "contentEncoding": "hex", + "format": "hex", "pattern": "^([0-9a-f][0-9a-f]){0,64}$" } } @@ -585,6 +588,7 @@ { "title": "Nonce from hash", "type": "string", + "format": "hex", "pattern": "^[0-9a-f]{64}$" } ] @@ -710,6 +714,7 @@ "description": "A mapping from GenesisHash to ProtocolParamUpdate", "patternProperties": { "^[0-9a-f]{56}$": { + "title": "ProtocolParamUpdate for a given GenesisHash", "$ref": "cardano-babbage.json#/definitions/ProtocolParamUpdate" } } @@ -724,11 +729,13 @@ "ScriptDataHash": { "title": "ScriptDataHash", "type": "string", + "format": "hex", "pattern": "^[0-9a-f]{64}$" }, "AuxiliaryDataHash": { "title": "Auxiliary Data Hash", "type": "string", + "format": "hex", "pattern": "^[0-9a-f]{64}$" }, "TransactionBody": { @@ -935,7 +942,7 @@ }, "value": { "type": "string", - "contentEncoding": "hex", + "format": "hex", "pattern": "^([0-9a-f][0-9a-f])*$" } } @@ -969,7 +976,7 @@ "title": "Ipv6", "description": "IPv6 address in fully-expanded form", "type": "string", - "pattern": "^([0-9a-f]{4}:){7}:[0-9a-f]{4}$" + "format": "ipv6" }, "Relay": { "discriminator": { @@ -1098,6 +1105,7 @@ "pool_metadata_hash": { "title": "Pool Metadata Hash", "type": "string", + "format": "hex", "pattern": "^[0-9a-f]{64}$" } }, @@ -1109,11 +1117,13 @@ "GenesisHash": { "title": "GenesisHash", "type": "string", + "format": "hex", "pattern": "^[0-9a-f]{56}$" }, "GenesisDelegateHash": { "title": "GenesisDelegateHash", "type": "string", + "format": "hex", "pattern": "^[0-9a-f]{56}$" }, "MIRPot": { @@ -1355,11 +1365,13 @@ "Ed25519Signature": { "title": "Ed25519Signature", "type": "string", + "format": "hex", "pattern": "^([0-9a-f][0-9a-f]){64}$" }, "Ed25519PublicKey": { "title": "Ed25519PublicKey", "type": "string", + "format": "hex", "pattern": "^([0-9a-f][0-9a-f]){32}$" }, "BootstrapWitness": { @@ -1367,10 +1379,12 @@ "properties": { "attributes": { "type": "string", + "format": "hex", "pattern": "^([0-9a-f][0-9a-f])*$" }, "chain_code": { "type": "string", + "format": "hex", "pattern": "^([0-9a-f][0-9a-f])*$" }, "signature": { From 88ce339eec4c6fc966ed171f49a920f218c22e6c Mon Sep 17 00:00:00 2001 From: Vladimir Kalnitsky Date: Wed, 21 Feb 2024 21:39:00 +0400 Subject: [PATCH 12/61] Fix `pattern` for ByteString - it can be empty --- CIP-XXXX/schema.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CIP-XXXX/schema.json b/CIP-XXXX/schema.json index 0bf6748449..d41d319d65 100644 --- a/CIP-XXXX/schema.json +++ b/CIP-XXXX/schema.json @@ -19,7 +19,7 @@ "description": "Arbitrary-length byte array", "type": "string", "format": "hex", - "pattern": "^([0-9a-f][0-9a-f])+$" + "pattern": "^([0-9a-f][0-9a-f])*$" }, "BigNum": { "title": "64-bit unsigned integer", From 13ec4cf32a1bc3cfbcc09013694a30f2dd4d920f Mon Sep 17 00:00:00 2001 From: Vladimir Kalnitsky Date: Thu, 22 Feb 2024 00:58:08 +0400 Subject: [PATCH 13/61] Add a README, rename the schema file --- CIP-XXXX/README.md | 181 ++++++++++++++++++ .../{schema.json => cardano-babbage.json} | 0 2 files changed, 181 insertions(+) create mode 100644 CIP-XXXX/README.md rename CIP-XXXX/{schema.json => cardano-babbage.json} (100%) diff --git a/CIP-XXXX/README.md b/CIP-XXXX/README.md new file mode 100644 index 0000000000..b204626d59 --- /dev/null +++ b/CIP-XXXX/README.md @@ -0,0 +1,181 @@ +--- +CIP: ? +Title: Standard JSON encoding for Domain Types +Category: Tools +Status: Proposed +Authors: + - Vladimir Kalnitsky +Implementors: [] +Discussions: + - https://github.com/cardano-foundation/cips/pulls/? +Created: 2024-02-22 +License: CC-BY-4.0 +--- + +## Abstract + +Canonical JSON encoding for Cardano domain types lets the ecosystem converge on a single way of serializing data to JSON, thus freeing the developers from repeating roughly the same, but slightly different encoding/decoding logic over and over. + +## Motivation: why is this CIP necessary? + +Cardano domain types have canonical CDDL definitions (for every era), but when it comes to use in web apps, where JSON is the universally accepted format, there is no definite standard. This CIP aims to change that. + +The full motivation text is provided in [CPS-11](https://github.com/cardano-foundation/CIPs/pull/742). + +## Specification + +This CIP is expected to contain multiple schema definitions for Cardano Eras starting from Babbage. + +- [Babbage](./cardano-babbage.json) + +### Schema Design Principles + +Below you can find some principles outlining the process of schema creation / modification. They are intended to be applied when there is a need to create a schema for a new Cardano era. + +#### Consistency with the previous versions + +To simplify transitions of dApps between eras, the scope of changes introduced to the schemas SHOULD be limited to the scope of CDDL changes. + +#### Scope of the Schema + +The schemas should cover `Block` type and all of its structural components, which corresponds to the scope of CDDL files located in [the ledger repo](https://github.com/IntersectMBO/cardano-ledger/). + +#### Absence of extensibility + +The schemas MUST NOT be extensible with additional properties. This may sound counter-intuitive and against the spirit of json-schema, but there are some motivations behind that: + +- More safety from typos: object fields that are optional may be specified with slightly incorrect names in dApps' code, leading to inability of the decoders to pick up the values, which may go unnoticed. +- Clear delineation between Cardano domain types and user dApp domain types: forcing the developers to store their dApp domain data separately from Cardano data, or close to it (as opposed to mixing these together in a single object) will indirectly motivate better structured dApp code. + +### Schema Conventions + +These conventions help to keep the schema uniform in style. + +### Encoding of mapping types + +`Map`-like container types should be encoded as arrays of key-value pairs. Uniqueness of `"key"` objects in a map MUST be preserved (but this property is not expressible via a schema). + +```json +"Map": { + "type": "array", + "items": { + "type": "object", + "properties": { + "key": ..., + "value": ... + }, + "additionalProperties": false + } +} +``` + +Implementations MUST consider mappings with conflicting keys invalid. + +### Encoding of variant types + +Encoding types with variable payloads MUST be done with the use of `oneOf` and an explicit discriminator property: `tag`: + +```json + "Credential": { + "type": "object", + "discriminator": { + "propertyName": "tag" + }, + "oneOf": [ + { + "type": "object", + "properties": { + "tag": { + "enum": [ + "pubkey_hash" + ] + }, + "value": { + "$ref": "cardano-babbage.json#/definitions/Ed25519KeyHash" + } + }, + "required": ["tag", "value"], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "tag": { + "enum": [ + "script_hash" + ] + }, + "value": { + "$ref": "cardano-babbage.json#/definitions/ScriptHash" + } + }, + "required": ["tag", "value"], + "additionalProperties": false + } + ] + }, +``` + +Other properties of a tagged object MUST be specified in lower-case snake-case. + +#### Encoding of enum types + +Enums are a special kind of variant types that carry no payloads. These must be encoded as string `enum`s. + +Lowercase snake case identifiers should be used for the options, e.g.: + +```json + "Language": { + "title": "Language", + "type": "string", + "enum": [ + "plutus_v1", + "plutus_v2" + ] + }, +``` + +### Encoding of record types + +All record types MUST be encoded as objects with explicit list of `required` properties, and `additionalProperties` set to `false` (see "absence of extensibility" chapter for the motivation behind this suggestion). + +### Encoding of nominal type synonyms + +Some of the types have identical representations, differing only by nominal name. For example, Slot domain type is expressed as `uint` in CDDL. + +For these types, their nominal name should not have a separate definition in the json-schema, and the "representation type" should be used via a `$ref` instead. The domain type name SHOULD be included as `title` string at the point of usage. + +### Additional format types + +Some non-standard `format` types are used: + +- `hex` +- `bech32` +- `base58` + +TODO: describe the formats + +## Limitations + +### Byte length limits for strings + +In CDDL, the length of a `tstr` value gives the number of bytes, but in `json-schema` there is no way to specify restrictions on byte lengths. So, `maxLength` is not the correct way of specifying the limits, but it is still useful, because no string longer than 64 *characters* satisfies the 64-byte limit. + +## Rationale: how does this CIP achieve its goals? + +## Path to Active + +- [ ] Complete the specification +- [ ] Provide an implementation of validating functions that uses this json-schema +- [ ] Collect a list of cardano domain types implementations and negotiate transition to the specified formats with maintainers (if it makes sense and is possible) + +### Acceptance Criteria + +### Implementation Plan + + +## Copyright + + +[CC-BY-4.0]: https://creativecommons.org/licenses/by/4.0/legalcode +[Apache-2.0]: http://www.apache.org/licenses/LICENSE-2.0 diff --git a/CIP-XXXX/schema.json b/CIP-XXXX/cardano-babbage.json similarity index 100% rename from CIP-XXXX/schema.json rename to CIP-XXXX/cardano-babbage.json From 746debe80f20003f8a28782eb8d52105b87fdb0d Mon Sep 17 00:00:00 2001 From: Vladimir Kalnitsky Date: Thu, 22 Feb 2024 16:10:34 +0300 Subject: [PATCH 14/61] Apply suggestions from code review by Ryun1 Co-authored-by: Ryan Williams <44342099+Ryun1@users.noreply.github.com> --- CIP-XXXX/README.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/CIP-XXXX/README.md b/CIP-XXXX/README.md index b204626d59..e91bee120d 100644 --- a/CIP-XXXX/README.md +++ b/CIP-XXXX/README.md @@ -7,7 +7,7 @@ Authors: - Vladimir Kalnitsky Implementors: [] Discussions: - - https://github.com/cardano-foundation/cips/pulls/? + - https://github.com/cardano-foundation/cips/pulls/766 Created: 2024-02-22 License: CC-BY-4.0 --- @@ -20,7 +20,7 @@ Canonical JSON encoding for Cardano domain types lets the ecosystem converge on Cardano domain types have canonical CDDL definitions (for every era), but when it comes to use in web apps, where JSON is the universally accepted format, there is no definite standard. This CIP aims to change that. -The full motivation text is provided in [CPS-11](https://github.com/cardano-foundation/CIPs/pull/742). +The full motivation text is provided in [CPS-11 | Universal JSON Encoding for Domain Types](https://github.com/cardano-foundation/CIPs/pull/742). ## Specification @@ -175,7 +175,8 @@ In CDDL, the length of a `tstr` value gives the number of bytes, but in `json-sc ## Copyright - + +This CIP is licensed under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). [CC-BY-4.0]: https://creativecommons.org/licenses/by/4.0/legalcode [Apache-2.0]: http://www.apache.org/licenses/LICENSE-2.0 From 06cf0217ca344c8754d9ebcd3769047597835ffb Mon Sep 17 00:00:00 2001 From: Vladimir Kalnitsky Date: Thu, 22 Feb 2024 17:28:05 +0400 Subject: [PATCH 15/61] Fix header layout --- CIP-XXXX/README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/CIP-XXXX/README.md b/CIP-XXXX/README.md index e91bee120d..a6d1c7cf18 100644 --- a/CIP-XXXX/README.md +++ b/CIP-XXXX/README.md @@ -51,7 +51,7 @@ The schemas MUST NOT be extensible with additional properties. This may sound co These conventions help to keep the schema uniform in style. -### Encoding of mapping types +#### Encoding of mapping types `Map`-like container types should be encoded as arrays of key-value pairs. Uniqueness of `"key"` objects in a map MUST be preserved (but this property is not expressible via a schema). @@ -71,7 +71,7 @@ These conventions help to keep the schema uniform in style. Implementations MUST consider mappings with conflicting keys invalid. -### Encoding of variant types +#### Encoding of variant types Encoding types with variable payloads MUST be done with the use of `oneOf` and an explicit discriminator property: `tag`: @@ -135,11 +135,11 @@ Lowercase snake case identifiers should be used for the options, e.g.: }, ``` -### Encoding of record types +#### Encoding of record types All record types MUST be encoded as objects with explicit list of `required` properties, and `additionalProperties` set to `false` (see "absence of extensibility" chapter for the motivation behind this suggestion). -### Encoding of nominal type synonyms +#### Encoding of nominal type synonyms Some of the types have identical representations, differing only by nominal name. For example, Slot domain type is expressed as `uint` in CDDL. @@ -155,9 +155,9 @@ Some non-standard `format` types are used: TODO: describe the formats -## Limitations +### Limitations -### Byte length limits for strings +#### Byte length limits for strings In CDDL, the length of a `tstr` value gives the number of bytes, but in `json-schema` there is no way to specify restrictions on byte lengths. So, `maxLength` is not the correct way of specifying the limits, but it is still useful, because no string longer than 64 *characters* satisfies the 64-byte limit. From f01e7e7f49de789fa9a1d6ee11ef5741aeabde20 Mon Sep 17 00:00:00 2001 From: Vladimir Kalnitsky Date: Thu, 22 Feb 2024 17:28:38 +0400 Subject: [PATCH 16/61] Remove a dead link --- CIP-XXXX/README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/CIP-XXXX/README.md b/CIP-XXXX/README.md index a6d1c7cf18..1358b47733 100644 --- a/CIP-XXXX/README.md +++ b/CIP-XXXX/README.md @@ -179,4 +179,3 @@ In CDDL, the length of a `tstr` value gives the number of bytes, but in `json-sc This CIP is licensed under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). [CC-BY-4.0]: https://creativecommons.org/licenses/by/4.0/legalcode -[Apache-2.0]: http://www.apache.org/licenses/LICENSE-2.0 From b259b4df6e481ea9b86aff414b5e0e5058e5984e Mon Sep 17 00:00:00 2001 From: Vladimir Kalnitsky Date: Thu, 22 Feb 2024 18:16:11 +0400 Subject: [PATCH 17/61] Expand "Limitations", add info on encoding of binary types --- CIP-XXXX/README.md | 30 +++++++++++++++++++++++++----- 1 file changed, 25 insertions(+), 5 deletions(-) diff --git a/CIP-XXXX/README.md b/CIP-XXXX/README.md index 1358b47733..53298558f5 100644 --- a/CIP-XXXX/README.md +++ b/CIP-XXXX/README.md @@ -51,9 +51,13 @@ The schemas MUST NOT be extensible with additional properties. This may sound co These conventions help to keep the schema uniform in style. +#### Encoding of binary types + +Binary data MUST be encoded as lower-case hexademical strings. Restricting the character set to lower-case letters (`a-f`) allows for comparisons and equality checks without the need to normalize the values to a uniform case. + #### Encoding of mapping types -`Map`-like container types should be encoded as arrays of key-value pairs. Uniqueness of `"key"` objects in a map MUST be preserved (but this property is not expressible via a schema). +`Map`-like container types MUST be encoded as arrays of key-value pairs. Uniqueness of `"key"` objects in a map MUST be preserved (but this property is not expressible via a schema). ```json "Map": { @@ -120,9 +124,9 @@ Other properties of a tagged object MUST be specified in lower-case snake-case. #### Encoding of enum types -Enums are a special kind of variant types that carry no payloads. These must be encoded as string `enum`s. +Enums are a special kind of variant types that carry no payloads. These MUST be encoded as string `enum`s. -Lowercase snake case identifiers should be used for the options, e.g.: +Lowercase snake case identifiers MUST be used for the options, e.g.: ```json "Language": { @@ -141,9 +145,9 @@ All record types MUST be encoded as objects with explicit list of `required` pro #### Encoding of nominal type synonyms -Some of the types have identical representations, differing only by nominal name. For example, Slot domain type is expressed as `uint` in CDDL. +Some of the types have identical representations, differing only by nominal name. For example, `Slot` domain type is expressed as `uint` in CDDL. -For these types, their nominal name should not have a separate definition in the json-schema, and the "representation type" should be used via a `$ref` instead. The domain type name SHOULD be included as `title` string at the point of usage. +For these types, their nominal name SHOULD NOT have a separate definition in the json-schema, and the "representation type" should be used via a `$ref` instead. The domain type name SHOULD be included as `title` string at the point of usage. ### Additional format types @@ -157,6 +161,22 @@ TODO: describe the formats ### Limitations +JSON-schema does not allow to express certain properties of some of the types. + +#### Uniqueness of mapping keys + +See the chapter on encoding of mapping types. + +#### Bech32 and Base58 formats + +Validity of values of these types can't be expressed as a regular expression, so the implementations MAY validate them separately. + +#### Address types + +Bech32 strings are not always valid addresses: even if the prefixes are correct, the [binary layout of the payload](https://github.com/IntersectMBO/cardano-ledger/blob/f754084675a1decceed4f309814b09605f443dd5/libs/cardano-ledger-core/src/Cardano/Ledger/Address.hs#L603) must also be valid. + +The implementations MAY validate it separately. + #### Byte length limits for strings In CDDL, the length of a `tstr` value gives the number of bytes, but in `json-schema` there is no way to specify restrictions on byte lengths. So, `maxLength` is not the correct way of specifying the limits, but it is still useful, because no string longer than 64 *characters* satisfies the 64-byte limit. From 96acbaaedfc072cd6a0b0bdab27c99a0e86cbfaa Mon Sep 17 00:00:00 2001 From: Vladimir Kalnitsky Date: Fri, 23 Feb 2024 01:38:23 +0300 Subject: [PATCH 18/61] Fix RewardAddress prefix Co-authored-by: Ryan Williams <44342099+Ryun1@users.noreply.github.com> --- CIP-XXXX/cardano-babbage.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CIP-XXXX/cardano-babbage.json b/CIP-XXXX/cardano-babbage.json index d41d319d65..610780476c 100644 --- a/CIP-XXXX/cardano-babbage.json +++ b/CIP-XXXX/cardano-babbage.json @@ -43,7 +43,7 @@ "title": "RewardAddress", "type": "string", "format": "bech32", - "pattern": "^(addr1|addr_test1)[02-9ac-hj-np-z]*$" + "pattern": "^(stake1|stake_test1)[02-9ac-hj-np-z]*$" }, "ByronAddress": { "title": "ByronAddress", From b1bc4a13b961d965a72bd39f7be0f5313d233b86 Mon Sep 17 00:00:00 2001 From: Vladimir Kalnitsky Date: Fri, 23 Feb 2024 22:53:33 +0400 Subject: [PATCH 19/61] Add note on uniqueness of encoding & move scope of the schema section --- CIP-XXXX/README.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/CIP-XXXX/README.md b/CIP-XXXX/README.md index 53298558f5..e726b52f1f 100644 --- a/CIP-XXXX/README.md +++ b/CIP-XXXX/README.md @@ -28,17 +28,24 @@ This CIP is expected to contain multiple schema definitions for Cardano Eras sta - [Babbage](./cardano-babbage.json) +### Scope of the Schema + +The schemas should cover `Block` type and all of its structural components, which corresponds to the scope of CDDL files located in [the ledger repo](https://github.com/IntersectMBO/cardano-ledger/). + ### Schema Design Principles Below you can find some principles outlining the process of schema creation / modification. They are intended to be applied when there is a need to create a schema for a new Cardano era. +#### Uniqueness of encoding + +Every transaction (i.e. CBOR-encoded binary) must have exactly one valid JSON encoding, up to entry ordering in mappings (that are represented as key-value pairs). + +For a single JSON fixture, however, there are multiple variants of encoding it as CBOR. + #### Consistency with the previous versions To simplify transitions of dApps between eras, the scope of changes introduced to the schemas SHOULD be limited to the scope of CDDL changes. -#### Scope of the Schema - -The schemas should cover `Block` type and all of its structural components, which corresponds to the scope of CDDL files located in [the ledger repo](https://github.com/IntersectMBO/cardano-ledger/). #### Absence of extensibility From 07db939a26e03b7aac044b44bd47c9e2cf6bbfaa Mon Sep 17 00:00:00 2001 From: Vladimir Kalnitsky Date: Fri, 23 Feb 2024 22:54:52 +0400 Subject: [PATCH 20/61] Add TransactionMetadata, AuxiliaryData and Transaction types --- CIP-XXXX/cardano-babbage.json | 65 ++++++++++++++++++++++++++++++++++- 1 file changed, 64 insertions(+), 1 deletion(-) diff --git a/CIP-XXXX/cardano-babbage.json b/CIP-XXXX/cardano-babbage.json index 610780476c..a8fa39ed5c 100644 --- a/CIP-XXXX/cardano-babbage.json +++ b/CIP-XXXX/cardano-babbage.json @@ -732,12 +732,55 @@ "format": "hex", "pattern": "^[0-9a-f]{64}$" }, + "TransactionMetadata": { + "title": "TransactionMetadata", + "type": "array", + "items": { + "type": "object", + "properties": { + "key": { + "$ref": "cardano-babbage.json#/definitions/BigNum" + }, + "value": { + "$ref": "cardano-babbage.json#/definitions/TransactionMetadatum" + } + }, + "required": [ + "key", + "value" + ], + "additionalProperties": false + } + }, "AuxiliaryDataHash": { - "title": "Auxiliary Data Hash", + "title": "AuxiliaryDataHash", "type": "string", "format": "hex", "pattern": "^[0-9a-f]{64}$" }, + "AuxiliaryData": { + "title": "AuxiliaryData", + "type": "object", + "properties": { + "metadata": { + "$ref": "cardano-babbage.json#/definitions/TransactionMetadata" + }, + "native_scripts": { + "type": "array", + "items": { + "$ref": "cardano-babbage.json#/definitions/NativeScript" + } + }, + "plutus_scripts": { + "type": "array", + "items": { + "$ref": "cardano-babbage.json#/definitions/PlutusScript" + } + } + }, + "requiredProperties": [], + "additionalProperties": false + }, "TransactionBody": { "type": "object", "properties": { @@ -1494,6 +1537,26 @@ } }, "required": [] + }, + "Transaction": { + "type": "object", + "title": "Transaction", + "properties": { + "auxiliary_data": { + "$ref": "cardano-babbage.json#/definitions/AuxiliaryData" + }, + "body": { + "$ref": "cardano-babbage.json#/definitions/TransactionBody" + }, + "is_valid": { + "type": "boolean" + }, + "witness_set": { + "$ref": "cardano-babbage.json#/definitions/TransactionWitnessSet" + } + }, + "requiredProperties": ["body", "is_valid", "witness_set"], + "additionalProperties": false } } } From cfd5c588e9025c61f339bb9c08c9daefc330e54c Mon Sep 17 00:00:00 2001 From: Vladimir Kalnitsky Date: Sat, 24 Feb 2024 00:12:31 +0400 Subject: [PATCH 21/61] Typo: requiredProperties -> required --- CIP-XXXX/cardano-babbage.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CIP-XXXX/cardano-babbage.json b/CIP-XXXX/cardano-babbage.json index a8fa39ed5c..10d295b501 100644 --- a/CIP-XXXX/cardano-babbage.json +++ b/CIP-XXXX/cardano-babbage.json @@ -778,7 +778,7 @@ } } }, - "requiredProperties": [], + "required": [], "additionalProperties": false }, "TransactionBody": { @@ -1555,7 +1555,7 @@ "$ref": "cardano-babbage.json#/definitions/TransactionWitnessSet" } }, - "requiredProperties": ["body", "is_valid", "witness_set"], + "required": ["body", "is_valid", "witness_set"], "additionalProperties": false } } From 6fc991793d2e2a5033b306f36cc2bb220cd01fdd Mon Sep 17 00:00:00 2001 From: Vladimir Kalnitsky Date: Sat, 24 Feb 2024 00:17:16 +0400 Subject: [PATCH 22/61] Use uniform names for numeric types --- CIP-XXXX/cardano-babbage.json | 96 +++++++++++++++++------------------ 1 file changed, 48 insertions(+), 48 deletions(-) diff --git a/CIP-XXXX/cardano-babbage.json b/CIP-XXXX/cardano-babbage.json index 10d295b501..3087090e0a 100644 --- a/CIP-XXXX/cardano-babbage.json +++ b/CIP-XXXX/cardano-babbage.json @@ -21,19 +21,19 @@ "format": "hex", "pattern": "^([0-9a-f][0-9a-f])*$" }, - "BigNum": { + "UInt64": { "title": "64-bit unsigned integer", "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$", "format": "uint64" }, - "Int": { + "Int128": { "title": "128-bit signed integer", "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$", "format": "int128" }, - "UInt": { + "UInt32": { "title": "32-bit unsigned integer", "type": "integer", "minimum": 0, @@ -148,7 +148,7 @@ "type": "object", "patternProperties": { "^([0-9a-f][0-9a-f]){0,32}$": { - "$ref": "cardano-babbage.json#/definitions/BigNum" + "$ref": "cardano-babbage.json#/definitions/UInt64" } }, "additionalProperties": false @@ -161,7 +161,7 @@ "type": "object", "properties": { "coin": { - "$ref": "cardano-babbage.json#/definitions/BigNum" + "$ref": "cardano-babbage.json#/definitions/UInt64" }, "multiasset": { "$ref": "cardano-babbage.json#/definitions/MultiAsset" @@ -183,7 +183,7 @@ "$ref": "cardano-babbage.json#/definitions/TransactionHash" }, "index": { - "$ref": "cardano-babbage.json#/definitions/UInt" + "$ref": "cardano-babbage.json#/definitions/UInt32" } }, "required": ["transaction_id", "index"], @@ -270,7 +270,7 @@ } }, "n": { - "$ref": "cardano-babbage.json#/definitions/UInt" + "$ref": "cardano-babbage.json#/definitions/UInt32" } }, "additionalProperties": false, @@ -286,7 +286,7 @@ ] }, "slot": { - "$ref": "cardano-babbage.json#/definitions/BigNum" + "$ref": "cardano-babbage.json#/definitions/UInt64" } }, "additionalProperties": false, @@ -302,7 +302,7 @@ ] }, "slot": { - "$ref": "cardano-babbage.json#/definitions/BigNum" + "$ref": "cardano-babbage.json#/definitions/UInt64" } }, "additionalProperties": false, @@ -483,7 +483,7 @@ ] }, "value": { - "$ref": "cardano-babbage.json#/definitions/Int" + "$ref": "cardano-babbage.json#/definitions/Int128" } }, "required": [ "tag", "value" ], @@ -533,7 +533,7 @@ "title": "CostModel", "type": "array", "items": { - "$ref": "cardano-babbage.json#/definitions/Int" + "$ref": "cardano-babbage.json#/definitions/Int128" }, "maxLength": 166, "minLength": 166 @@ -542,7 +542,7 @@ "title": "CostModel", "type": "array", "items": { - "$ref": "cardano-babbage.json#/definitions/Int" + "$ref": "cardano-babbage.json#/definitions/Int128" }, "maxLength": 175, "minLength": 175 @@ -598,10 +598,10 @@ "type": "object", "properties": { "mem": { - "$ref": "cardano-babbage.json#/definitions/BigNum" + "$ref": "cardano-babbage.json#/definitions/UInt64" }, "steps": { - "$ref": "cardano-babbage.json#/definitions/BigNum" + "$ref": "cardano-babbage.json#/definitions/UInt64" } }, "required": [ "mem", "steps" ], @@ -612,10 +612,10 @@ "type": "object", "properties": { "major": { - "$ref": "cardano-babbage.json#/definitions/UInt" + "$ref": "cardano-babbage.json#/definitions/UInt32" }, "minor": { - "$ref": "cardano-babbage.json#/definitions/UInt" + "$ref": "cardano-babbage.json#/definitions/UInt32" } }, "required": [ "major", "minor" ], @@ -626,10 +626,10 @@ "title": "ProtocolParamUpdate", "properties": { "ada_per_utxo_byte": { - "$ref": "cardano-babbage.json#/definitions/BigNum" + "$ref": "cardano-babbage.json#/definitions/UInt64" }, "collateral_percentage": { - "$ref": "cardano-babbage.json#/definitions/UInt" + "$ref": "cardano-babbage.json#/definitions/UInt32" }, "cost_models": { "$ref": "cardano-babbage.json#/definitions/CostModels" @@ -647,46 +647,46 @@ "$ref": "cardano-babbage.json#/definitions/Nonce" }, "key_deposit": { - "$ref": "cardano-babbage.json#/definitions/BigNum" + "$ref": "cardano-babbage.json#/definitions/UInt64" }, "max_block_body_size": { - "$ref": "cardano-babbage.json#/definitions/UInt" + "$ref": "cardano-babbage.json#/definitions/UInt32" }, "max_block_ex_units": { "$ref": "cardano-babbage.json#/definitions/ExUnits" }, "max_block_header_size": { - "$ref": "cardano-babbage.json#/definitions/UInt" + "$ref": "cardano-babbage.json#/definitions/UInt32" }, "max_collateral_inputs": { - "$ref": "cardano-babbage.json#/definitions/UInt" + "$ref": "cardano-babbage.json#/definitions/UInt32" }, "max_epoch": { - "$ref": "cardano-babbage.json#/definitions/UInt" + "$ref": "cardano-babbage.json#/definitions/UInt32" }, "max_tx_ex_units": { "$ref": "cardano-babbage.json#/definitions/ExUnits" }, "max_tx_size": { - "$ref": "cardano-babbage.json#/definitions/UInt" + "$ref": "cardano-babbage.json#/definitions/UInt32" }, "max_value_size": { - "$ref": "cardano-babbage.json#/definitions/UInt" + "$ref": "cardano-babbage.json#/definitions/UInt32" }, "min_pool_cost": { - "$ref": "cardano-babbage.json#/definitions/BigNum" + "$ref": "cardano-babbage.json#/definitions/UInt64" }, "minfee_a": { - "$ref": "cardano-babbage.json#/definitions/BigNum" + "$ref": "cardano-babbage.json#/definitions/UInt64" }, "minfee_b": { - "$ref": "cardano-babbage.json#/definitions/BigNum" + "$ref": "cardano-babbage.json#/definitions/UInt64" }, "n_opt": { - "$ref": "cardano-babbage.json#/definitions/Int" + "$ref": "cardano-babbage.json#/definitions/Int128" }, "pool_deposit": { - "$ref": "cardano-babbage.json#/definitions/BigNum" + "$ref": "cardano-babbage.json#/definitions/UInt64" }, "pool_pledge_influence": { "$ref": "cardano-babbage.json#/definitions/UnitInterval" @@ -706,7 +706,7 @@ "title": "Update", "properties": { "epoch": { - "$ref": "cardano-babbage.json#/definitions/UInt" + "$ref": "cardano-babbage.json#/definitions/UInt32" }, "proposed_protocol_parameter_updates": { "type": "object", @@ -739,7 +739,7 @@ "type": "object", "properties": { "key": { - "$ref": "cardano-babbage.json#/definitions/BigNum" + "$ref": "cardano-babbage.json#/definitions/UInt64" }, "value": { "$ref": "cardano-babbage.json#/definitions/TransactionMetadatum" @@ -800,7 +800,7 @@ } }, "fee": { - "$ref": "cardano-babbage.json#/definitions/BigNum" + "$ref": "cardano-babbage.json#/definitions/UInt64" }, "certs": { "type": "array", @@ -849,16 +849,16 @@ "$ref": "cardano-babbage.json#/definitions/ScriptDataHash" }, "total_collateral": { - "$ref": "cardano-babbage.json#/definitions/BigNum" + "$ref": "cardano-babbage.json#/definitions/UInt64" }, "ttl": { - "$ref": "cardano-babbage.json#/definitions/BigNum" + "$ref": "cardano-babbage.json#/definitions/UInt64" }, "update": { "$ref": "cardano-babbage.json#/definitions/Update" }, "validity_start_interval": { - "$ref": "cardano-babbage.json#/definitions/BigNum" + "$ref": "cardano-babbage.json#/definitions/UInt64" }, "withdrawals": { "type": "array", @@ -869,7 +869,7 @@ "$ref": "cardano-babbage.json#/definitions/RewardAddress" }, "value": { - "$ref": "cardano-babbage.json#/definitions/BigNum" + "$ref": "cardano-babbage.json#/definitions/UInt64" } }, "additionalProperties": false @@ -924,7 +924,7 @@ ] }, "alternative": { - "$ref": "cardano-babbage.json#/definitions/BigNum" + "$ref": "cardano-babbage.json#/definitions/UInt64" }, "data": { "type": "array", @@ -970,7 +970,7 @@ ] }, "value": { - "$ref": "cardano-babbage.json#/definitions/BigInt" + "$ref": "cardano-babbage.json#/definitions/Iigint128" } } }, @@ -996,10 +996,10 @@ "type": "object", "properties": { "numerator": { - "$ref": "cardano-babbage.json#/definitions/BigNum" + "$ref": "cardano-babbage.json#/definitions/UInt64" }, "denominator": { - "$ref": "cardano-babbage.json#/definitions/BigNum" + "$ref": "cardano-babbage.json#/definitions/UInt64" } }, "additionalProperties": false @@ -1116,10 +1116,10 @@ "$ref": "cardano-babbage.json#/definitions/VRFKeyHash" }, "pledge": { - "$ref": "cardano-babbage.json#/definitions/BigNum" + "$ref": "cardano-babbage.json#/definitions/UInt64" }, "cost": { - "$ref": "cardano-babbage.json#/definitions/BigNum" + "$ref": "cardano-babbage.json#/definitions/UInt64" }, "margin": { "$ref": "cardano-babbage.json#/definitions/UnitInterval" @@ -1205,7 +1205,7 @@ "$ref": "cardano-babbage.json#/definitions/Credential" }, "value": { - "$ref": "cardano-babbage.json#/definitions/Int" + "$ref": "cardano-babbage.json#/definitions/Int128" } }, "required": [ @@ -1235,7 +1235,7 @@ "$ref": "cardano-babbage.json#/definitions/MIRPot" }, "amount": { - "$ref": "cardano-babbage.json#/definitions/BigNum" + "$ref": "cardano-babbage.json#/definitions/UInt64" } }, "additionalProperties": false, @@ -1333,7 +1333,7 @@ "$ref": "cardano-babbage.json#/definitions/Ed25519KeyHash" }, "epoch": { - "$ref": "cardano-babbage.json#/definitions/UInt" + "$ref": "cardano-babbage.json#/definitions/UInt32" } }, "required": ["tag", "pool_keyhash", "epoch"], @@ -1397,7 +1397,7 @@ "type": "object", "patternProperties": { "^([0-9a-f][0-9a-f]){0,32}$": { - "$ref": "cardano-babbage.json#/definitions/Int" + "$ref": "cardano-babbage.json#/definitions/Int128" } }, "additionalProperties": false @@ -1466,7 +1466,7 @@ "$ref": "cardano-babbage.json#/definitions/RedeemerTag" }, "index": { - "$ref": "cardano-babbage.json#/definitions/BigNum" + "$ref": "cardano-babbage.json#/definitions/UInt64" }, "ex_units": { "$ref": "cardano-babbage.json#/definitions/ExUnits" From 02ec737158b18eff2db2085dcca92987213a4854 Mon Sep 17 00:00:00 2001 From: Vladimir Kalnitsky Date: Wed, 28 Feb 2024 19:41:29 +0400 Subject: [PATCH 23/61] Complete the definitions + fixes --- CIP-XXXX/cardano-babbage.json | 282 +++++++++++++++++++++++++++++++--- 1 file changed, 260 insertions(+), 22 deletions(-) diff --git a/CIP-XXXX/cardano-babbage.json b/CIP-XXXX/cardano-babbage.json index 3087090e0a..ae97e21b88 100644 --- a/CIP-XXXX/cardano-babbage.json +++ b/CIP-XXXX/cardano-babbage.json @@ -167,14 +167,16 @@ "$ref": "cardano-babbage.json#/definitions/MultiAsset" } }, - "required": ["coin", "multiasset"], + "required": ["coin"], "additionalProperties": false }, "TransactionHash": { "title": "TransactionHash", "type": "string", "format": "hex", - "pattern": "^[0-9a-f]{64}$" + "pattern": "^[0-9a-f]{64}$", + "maxLength": 64, + "minLength": 64 }, "TransactionInput": { "type": "object", @@ -970,7 +972,7 @@ ] }, "value": { - "$ref": "cardano-babbage.json#/definitions/Iigint128" + "$ref": "cardano-babbage.json#/definitions/Int128" } } }, @@ -1009,18 +1011,17 @@ "type": "string", "pattern": "^((25[0-5]|(2[0-4]|1\\d|[1-9]|)\\d)\\.){3}(25[0-5]|(2[0-4]|1\\d|[1-9]|)\\d)$" }, - "DNSName": { - "title": "DNSName", - "description": "", - "type": "string", - "maxLength": 64 - }, "Ipv6": { "title": "Ipv6", "description": "IPv6 address in fully-expanded form", "type": "string", "format": "ipv6" }, + "DNSName": { + "title": "DNSName", + "type": "string", + "maxLength": 64 + }, "Relay": { "discriminator": { "propertyName": "tag" @@ -1106,8 +1107,25 @@ "type": "string", "maxLength": 64 }, + "PoolMetadata": { + "type": "object", + "properties": { + "url": { + "$ref": "cardano-babbage.json#/definitions/URL" + }, + "pool_metadata_hash": { + "title": "Pool Metadata Hash", + "type": "string", + "format": "hex", + "pattern": "^[0-9a-f]{64}$" + } + }, + "additionalProperties": false, + "required": ["url", "pool_metadata_hash"] + }, "PoolParams": { "type": "object", + "title": "PoolParams", "properties": { "operator": { "$ref": "cardano-babbage.json#/definitions/Ed25519KeyHash" @@ -1140,21 +1158,19 @@ } }, "pool_metadata": { - "type": "object", - "properties": { - "url": { - "$ref": "cardano-babbage.json#/definitions/URL" - }, - "pool_metadata_hash": { - "title": "Pool Metadata Hash", - "type": "string", - "format": "hex", - "pattern": "^[0-9a-f]{64}$" - } - }, - "additionalProperties": false + "$ref": "cardano-babbage.json#/definitions/PoolMetadata" } }, + "required": [ + "cost", + "margin", + "operator", + "pledge", + "pool_owners", + "relays", + "reward_account", + "vrf_keyhash" + ], "additionalProperties": false }, "GenesisHash": { @@ -1557,6 +1573,228 @@ }, "required": ["body", "is_valid", "witness_set"], "additionalProperties": false + }, + "AuxiliaryDataSet": { + "type": "object", + "title": "AuxiliaryDataSet", + "description": "A mapping from numbers to AuxiliaryData", + "patternProperties": { + "^(0|[1-9][0-9]*)$": { + "$ref": "cardano-babbage.json#/definitions/AuxiliaryData" + } + }, + "additionalProperties": false + }, + "VRFCert": { + "type": "object", + "title": "VRFCert", + "properties": { + "output": { + "$ref": "cardano-babbage.json#/definitions/ByteString" + }, + "proof": { + "$ref": "cardano-babbage.json#/definitions/ByteString" + } + }, + "required": ["output", "proof"], + "additionalProperties": false + }, + "HeaderLeaderCert": { + "type": "object", + "discriminator": { + "propertyName": "tag" + }, + "oneOf": [ + { + "type": "object", + "properties": { + "tag": { + "enum": [ + "nonce_and_leader" + ] + }, + "nonce": { + "$ref": "cardano-babbage.json#/definitions/VRFCert" + }, + "leader": { + "$ref": "cardano-babbage.json#/definitions/VRFCert" + } + }, + "required": ["tag", "nonce", "leader"], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "tag": { + "enum": [ + "vrf_result" + ] + }, + "cert": { + "$ref": "cardano-babbage.json#/definitions/VRFCert" + } + }, + "required": ["tag", "cert"], + "additionalProperties": false + } + ] + }, + "KESVKey": { + "title": "KESVKey", + "type": "string", + "format": "hex", + "pattern": "^[0-9a-f]{64}$", + "maxLength": 64, + "minLength": 64 + }, + "BlockHash": { + "title": "BlockHash", + "type": "string", + "format": "hex", + "pattern": "^[0-9a-f]{64}$", + "maxLength": 64, + "minLength": 64 + }, + "VRFVKey": { + "title": "KESVKey", + "type": "string", + "format": "hex", + "pattern": "^[0-9a-f]{64}$", + "maxLength": 64, + "minLength": 64 + }, + "KESSignature": { + "title": "KESSignature", + "type": "string", + "format": "hex", + "pattern": "^[0-9a-f]{896}$", + "maxLength": 896, + "minLength": 896 + }, + "OperationalCert": { + "type": "object", + "properties": { + "hot_vkey": { + "$ref": "cardano-babbage.json#/definitions/KESVKey" + }, + "kes_period": { + "$ref": "cardano-babbage.json#/definitions/UInt32" + }, + "sequence_number": { + "$ref": "cardano-babbage.json#/definitions/UInt32" + }, + "sigma": { + "$ref": "cardano-babbage.json#/definitions/Ed25519Signature" + } + }, + "required": ["hot_vkey", "kes_period", "sequence_number", "sigma"], + "additionalProperties": false + }, + "HeaderBody": { + "type": "object", + "properties": { + "block_body_hash": { + "$ref": "cardano-babbage.json#/definitions/BlockHash" + }, + "block_body_size": { + "$ref": "cardano-babbage.json#/definitions/UInt32" + }, + "block_number": { + "$ref": "cardano-babbage.json#/definitions/UInt32" + }, + "issuer_vkey": { + "$ref": "cardano-babbage.json#/definitions/Ed25519PublicKey" + }, + "leader_cert": { + "$ref": "cardano-babbage.json#/definitions/HeaderLeaderCert" + }, + "operational_cert": { + "$ref": "cardano-babbage.json#/definitions/OperationalCert" + }, + "prev_hash": { + "$ref": "cardano-babbage.json#/definitions/BlockHash" + }, + "protocol_version": { + "$ref": "cardano-babbage.json#/definitions/ProtocolVersion" + }, + "slot": { + "$ref": "cardano-babbage.json#/definitions/UInt64" + }, + "vrf_vkey": { + "$ref": "cardano-babbage.json#/definitions/VRFVKey" + } + }, + "additionalProperties": false, + "required": [ + "block_body_hash", + "block_body_size", + "block_number", + "issuer_vkey", + "leader_cert", + "operational_cert", + "protocol_version", + "slot", + "vrf_vkey" + ] + }, + "Header": { + "type": "object", + "properties": { + "body_signature": { + "$ref": "cardano-babbage.json#/definitions/KESSignature" + }, + "header_body": { + "$ref": "cardano-babbage.json#/definitions/HeaderBody" + } + }, + "required": [ "body_signature", "header_body" ], + "additionalProperties": false + }, + "Block": { + "type": "object", + "title": "Block", + "properties": { + "auxiliary_data_set": { + "$ref": "cardano-babbage.json#/definitions/AuxiliaryDataSet" + }, + "header": { + "$ref": "cardano-babbage.json#/definitions/Header" + }, + "invalid_transactions": { + "type": "array", + "items": { + "allOf": [ + { + "title": "TransactionIndex" + }, + { + "$ref": "cardano-babbage.json#/definitions/UInt32" + } + ] + } + }, + "transaction_bodies": { + "type": "array", + "items": { + "$ref": "cardano-babbage.json#/definitions/TransactionBody" + } + }, + "transaction_witness_sets": { + "type": "array", + "items": { + "$ref": "cardano-babbage.json#/definitions/TransactionWitnessSet" + } + } + }, + "additionalProperties": false, + "required": [ + "auxiliary_data_set", + "header", + "invalid_transactions", + "transaction_bodies", + "transaction_witness_sets" + ] } } } From 40629717da45224972b4808e09d916bfb973dbec Mon Sep 17 00:00:00 2001 From: Vladimir Kalnitsky Date: Wed, 28 Feb 2024 21:11:32 +0400 Subject: [PATCH 24/61] Fix PlutusScript, add titles everywhere --- CIP-XXXX/cardano-babbage.json | 66 ++++++++++++++++++++++++----------- 1 file changed, 46 insertions(+), 20 deletions(-) diff --git a/CIP-XXXX/cardano-babbage.json b/CIP-XXXX/cardano-babbage.json index ae97e21b88..fc6b228a41 100644 --- a/CIP-XXXX/cardano-babbage.json +++ b/CIP-XXXX/cardano-babbage.json @@ -4,7 +4,7 @@ "title": "Cardano Domain Types", "definitions": { "BigInt": { - "title": "Long signed integer", + "title": "BigInt", "type": "string", "description": "A long integer domain type", "pattern": "^-?(0|[1-9][0-9]*)$", @@ -22,19 +22,22 @@ "pattern": "^([0-9a-f][0-9a-f])*$" }, "UInt64": { - "title": "64-bit unsigned integer", + "title": "UInt64", + "description": "64-bit unsigned integer", "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$", "format": "uint64" }, "Int128": { - "title": "128-bit signed integer", + "title": "Int128", + "description": "128-bit signed integer", "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$", "format": "int128" }, "UInt32": { - "title": "32-bit unsigned integer", + "title": "UInt32", + "description": "32-bit unsigned integer", "type": "integer", "minimum": 0, "maximum": 4294967295 @@ -102,6 +105,7 @@ "pattern": "^[0-9a-f]{56}$" }, "Credential": { + "title": "Credential", "type": "object", "discriminator": { "propertyName": "tag" @@ -179,6 +183,7 @@ "minLength": 64 }, "TransactionInput": { + "title": "TransactionInput", "type": "object", "properties": { "transaction_id": { @@ -192,9 +197,20 @@ "additionalProperties": false }, "PlutusScript": { - "type": "string", - "format": "hex", - "pattern": "^([0-9a-f][0-9a-f])+$" + "title": "PlutusScript", + "type": "object", + "properties": { + "language": { + "$ref": "cardano-babbage.json#/definitions/Language" + }, + "bytes": { + "type": "string", + "format": "hex", + "pattern": "^([0-9a-f][0-9a-f])+$" + } + }, + "required": ["language", "bytes"], + "additionalProperties": false }, "NativeScript": { "title": "NativeScript", @@ -532,7 +548,7 @@ ] }, "PlutusV1CostModel": { - "title": "CostModel", + "title": "PlutusV1CostModel", "type": "array", "items": { "$ref": "cardano-babbage.json#/definitions/Int128" @@ -541,7 +557,7 @@ "minLength": 166 }, "PlutusV2CostModel": { - "title": "CostModel", + "title": "PlutusV2CostModel", "type": "array", "items": { "$ref": "cardano-babbage.json#/definitions/Int128" @@ -553,10 +569,10 @@ "title": "CostModels", "type": "object", "properties": { - "PlutusV1": { + "plutus_v1": { "$ref": "cardano-babbage.json#/definitions/PlutusV1CostModel" }, - "PlutusV2": { + "plutus_v1": { "$ref": "cardano-babbage.json#/definitions/PlutusV2CostModel" } }, @@ -624,8 +640,8 @@ "additionalProperties": false }, "ProtocolParamUpdate": { - "type": "object", "title": "ProtocolParamUpdate", + "type": "object", "properties": { "ada_per_utxo_byte": { "$ref": "cardano-babbage.json#/definitions/UInt64" @@ -704,8 +720,8 @@ "required": [] }, "Update": { - "type": "object", "title": "Update", + "type": "object", "properties": { "epoch": { "$ref": "cardano-babbage.json#/definitions/UInt32" @@ -784,6 +800,7 @@ "additionalProperties": false }, "TransactionBody": { + "title": "TransactionBody", "type": "object", "properties": { "auxiliary_data_hash": { @@ -995,6 +1012,7 @@ ] }, "UnitInterval": { + "title": "UnitInterval", "type": "object", "properties": { "numerator": { @@ -1007,13 +1025,14 @@ "additionalProperties": false }, "Ipv4": { - "title": "IPv4 Address", + "title": "Ipv4", + "description": "IPv4 Address", "type": "string", "pattern": "^((25[0-5]|(2[0-4]|1\\d|[1-9]|)\\d)\\.){3}(25[0-5]|(2[0-4]|1\\d|[1-9]|)\\d)$" }, "Ipv6": { "title": "Ipv6", - "description": "IPv6 address in fully-expanded form", + "description": "IPv6 address", "type": "string", "format": "ipv6" }, @@ -1023,6 +1042,7 @@ "maxLength": 64 }, "Relay": { + "title": "Relay", "discriminator": { "propertyName": "tag" }, @@ -1095,8 +1115,8 @@ ] }, "VRFKeyHash": { - "type": "string", "title": "VRFKeyHash", + "type": "string", "description": "blake2b_256 digest of a VRF verification key, encoded as bech32", "type": "string", "pattern": "^vrf_vkh[02-9ac-hj-np-z]*" @@ -1108,6 +1128,7 @@ "maxLength": 64 }, "PoolMetadata": { + "title": "PoolMetadata", "type": "object", "properties": { "url": { @@ -1124,8 +1145,8 @@ "required": ["url", "pool_metadata_hash"] }, "PoolParams": { - "type": "object", "title": "PoolParams", + "type": "object", "properties": { "operator": { "$ref": "cardano-babbage.json#/definitions/Ed25519KeyHash" @@ -1434,6 +1455,7 @@ "pattern": "^([0-9a-f][0-9a-f]){32}$" }, "BootstrapWitness": { + "title": "BootstrapWitness", "type": "object", "properties": { "attributes": { @@ -1586,8 +1608,8 @@ "additionalProperties": false }, "VRFCert": { - "type": "object", "title": "VRFCert", + "type": "object", "properties": { "output": { "$ref": "cardano-babbage.json#/definitions/ByteString" @@ -1600,6 +1622,7 @@ "additionalProperties": false }, "HeaderLeaderCert": { + "title": "HeaderLeaderCert", "type": "object", "discriminator": { "propertyName": "tag" @@ -1657,7 +1680,7 @@ "minLength": 64 }, "VRFVKey": { - "title": "KESVKey", + "title": "VRFVKey", "type": "string", "format": "hex", "pattern": "^[0-9a-f]{64}$", @@ -1673,6 +1696,7 @@ "minLength": 896 }, "OperationalCert": { + "title": "OperationalCert", "type": "object", "properties": { "hot_vkey": { @@ -1692,6 +1716,7 @@ "additionalProperties": false }, "HeaderBody": { + "title": "HeaderBody", "type": "object", "properties": { "block_body_hash": { @@ -1739,6 +1764,7 @@ ] }, "Header": { + "title": "Header", "type": "object", "properties": { "body_signature": { @@ -1752,8 +1778,8 @@ "additionalProperties": false }, "Block": { - "type": "object", "title": "Block", + "type": "object", "properties": { "auxiliary_data_set": { "$ref": "cardano-babbage.json#/definitions/AuxiliaryDataSet" From b6aaea78dbb8ec006a713e63fed8bc5f2970381d Mon Sep 17 00:00:00 2001 From: Vladimir Kalnitsky Date: Wed, 28 Feb 2024 21:32:35 +0400 Subject: [PATCH 25/61] Add a note on AuxiliaryData --- CIP-XXXX/README.md | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/CIP-XXXX/README.md b/CIP-XXXX/README.md index e726b52f1f..a55762426d 100644 --- a/CIP-XXXX/README.md +++ b/CIP-XXXX/README.md @@ -188,6 +188,48 @@ The implementations MAY validate it separately. In CDDL, the length of a `tstr` value gives the number of bytes, but in `json-schema` there is no way to specify restrictions on byte lengths. So, `maxLength` is not the correct way of specifying the limits, but it is still useful, because no string longer than 64 *characters* satisfies the 64-byte limit. +#### Auxiliary Data encoding + +`auxiliary_data` CDDL type is handled specially. + +```cddl +auxiliary_data = + metadata ; Shelley + / [ transaction_metadata: metadata ; Shelley-ma + , auxiliary_scripts: [ * native_script ] + ] + / #6.259({ ? 0 => metadata ; Alonzo and beyond + , ? 1 => [ * native_script ] + , ? 2 => [ * plutus_v1_script ] + , ? 3 => [ * plutus_v2_script ] + }) +``` + +Instead of providing all three variants of encoding, we base the schema on the one that is the most general (the last one): + +```json + "AuxiliaryData": { + "properties": { + "metadata": { + "$ref": "cardano-babbage.json#/definitions/TransactionMetadata" + }, + "native_scripts": { + "type": "array", + "items": { + "$ref": "cardano-babbage.json#/definitions/NativeScript" + } + }, + "plutus_scripts": { + "type": "array", + "items": { + "$ref": "cardano-babbage.json#/definitions/PlutusScript" + } + } + }, +``` + +It is up to implementors to decide how to serialize the values into CBOR. The property we want to maintain is preserved regardless of the choice: for every block binary there is exactly one JSON encoding. + ## Rationale: how does this CIP achieve its goals? ## Path to Active From ea31486f175816353a997b74eab0e17b82ed76d0 Mon Sep 17 00:00:00 2001 From: Robert Phair Date: Thu, 7 Mar 2024 14:32:34 +0530 Subject: [PATCH 26/61] fix bracket mismatch in code sample --- CIP-XXXX/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CIP-XXXX/README.md b/CIP-XXXX/README.md index a55762426d..11cd8a1c78 100644 --- a/CIP-XXXX/README.md +++ b/CIP-XXXX/README.md @@ -226,6 +226,7 @@ Instead of providing all three variants of encoding, we base the schema on the o } } }, + }, ``` It is up to implementors to decide how to serialize the values into CBOR. The property we want to maintain is preserved regardless of the choice: for every block binary there is exactly one JSON encoding. From f0d2f63c978cf85b170807c2fc2502ddfdf33ae9 Mon Sep 17 00:00:00 2001 From: Robert Phair Date: Thu, 7 Mar 2024 14:34:11 +0530 Subject: [PATCH 27/61] setting candidate CIP number to 116 --- CIP-XXXX/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CIP-XXXX/README.md b/CIP-XXXX/README.md index 11cd8a1c78..7c2e5e13ac 100644 --- a/CIP-XXXX/README.md +++ b/CIP-XXXX/README.md @@ -1,5 +1,5 @@ --- -CIP: ? +CIP: 116 Title: Standard JSON encoding for Domain Types Category: Tools Status: Proposed From d90f1fb1e780337d02202f0e11d2f1bb53614363 Mon Sep 17 00:00:00 2001 From: Vladimir Kalnitsky Date: Thu, 21 Mar 2024 18:48:43 +0400 Subject: [PATCH 28/61] Fix suggested by Evgeny: Use BigInt in PlutusData --- CIP-XXXX/cardano-babbage.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CIP-XXXX/cardano-babbage.json b/CIP-XXXX/cardano-babbage.json index fc6b228a41..b1f6a65625 100644 --- a/CIP-XXXX/cardano-babbage.json +++ b/CIP-XXXX/cardano-babbage.json @@ -989,7 +989,7 @@ ] }, "value": { - "$ref": "cardano-babbage.json#/definitions/Int128" + "$ref": "cardano-babbage.json#/definitions/BigInt" } } }, From ed7c56d71c9f452cf9b87530e7963c5c6cd5a00b Mon Sep 17 00:00:00 2001 From: Vladimir Kalnitsky Date: Thu, 21 Mar 2024 18:50:42 +0400 Subject: [PATCH 29/61] Fix suggested by Evgeny --- CIP-XXXX/cardano-babbage.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CIP-XXXX/cardano-babbage.json b/CIP-XXXX/cardano-babbage.json index b1f6a65625..9626c4d7cc 100644 --- a/CIP-XXXX/cardano-babbage.json +++ b/CIP-XXXX/cardano-babbage.json @@ -572,7 +572,7 @@ "plutus_v1": { "$ref": "cardano-babbage.json#/definitions/PlutusV1CostModel" }, - "plutus_v1": { + "plutus_v2": { "$ref": "cardano-babbage.json#/definitions/PlutusV2CostModel" } }, From c8b53015ddbdf808ec7a361038fd7d55fea50219 Mon Sep 17 00:00:00 2001 From: Vladimir Kalnitsky Date: Thu, 11 Apr 2024 01:08:44 +0400 Subject: [PATCH 30/61] Apply suggestions + fixes --- CIP-XXXX/README.md | 22 +++++++++++++--------- CIP-XXXX/cardano-babbage.json | 3 +-- 2 files changed, 14 insertions(+), 11 deletions(-) diff --git a/CIP-XXXX/README.md b/CIP-XXXX/README.md index 7c2e5e13ac..0eb696792a 100644 --- a/CIP-XXXX/README.md +++ b/CIP-XXXX/README.md @@ -24,7 +24,7 @@ The full motivation text is provided in [CPS-11 | Universal JSON Encoding for Do ## Specification -This CIP is expected to contain multiple schema definitions for Cardano Eras starting from Babbage. +This CIP is expected to contain multiple schema definitions for Cardano Eras and breaking intra-era hardforks starting from Babbage. - [Babbage](./cardano-babbage.json) @@ -87,6 +87,7 @@ Implementations MUST consider mappings with conflicting keys invalid. Encoding types with variable payloads MUST be done with the use of `oneOf` and an explicit discriminator property: `tag`: ```json +{ "Credential": { "type": "object", "discriminator": { @@ -124,7 +125,8 @@ Encoding types with variable payloads MUST be done with the use of `oneOf` and a "additionalProperties": false } ] - }, + } +} ``` Other properties of a tagged object MUST be specified in lower-case snake-case. @@ -136,6 +138,7 @@ Enums are a special kind of variant types that carry no payloads. These MUST be Lowercase snake case identifiers MUST be used for the options, e.g.: ```json +{ "Language": { "title": "Language", "type": "string", @@ -143,7 +146,8 @@ Lowercase snake case identifiers MUST be used for the options, e.g.: "plutus_v1", "plutus_v2" ] - }, + } +} ``` #### Encoding of record types @@ -160,11 +164,9 @@ For these types, their nominal name SHOULD NOT have a separate definition in the Some non-standard `format` types are used: -- `hex` -- `bech32` -- `base58` - -TODO: describe the formats +- `hex` - lower-case hex-encoded byte string +- `bech32` - [bech32](https://en.bitcoin.it/wiki/Bech32) string +- `base58` - [base58](https://bitcoinwiki.org/wiki/base58) string ### Limitations @@ -208,6 +210,7 @@ auxiliary_data = Instead of providing all three variants of encoding, we base the schema on the one that is the most general (the last one): ```json +{ "AuxiliaryData": { "properties": { "metadata": { @@ -226,7 +229,8 @@ Instead of providing all three variants of encoding, we base the schema on the o } } }, - }, + } +} ``` It is up to implementors to decide how to serialize the values into CBOR. The property we want to maintain is preserved regardless of the choice: for every block binary there is exactly one JSON encoding. diff --git a/CIP-XXXX/cardano-babbage.json b/CIP-XXXX/cardano-babbage.json index 9626c4d7cc..95df810f73 100644 --- a/CIP-XXXX/cardano-babbage.json +++ b/CIP-XXXX/cardano-babbage.json @@ -1118,7 +1118,6 @@ "title": "VRFKeyHash", "type": "string", "description": "blake2b_256 digest of a VRF verification key, encoded as bech32", - "type": "string", "pattern": "^vrf_vkh[02-9ac-hj-np-z]*" }, "URL": { @@ -1434,7 +1433,7 @@ "type": "object", "patternProperties": { "^([0-9a-f][0-9a-f]){0,32}$": { - "$ref": "cardano-babbage.json#/definitions/Int128" + "$ref": "cardano-babbage.json#/definitions/Int64" } }, "additionalProperties": false From 1498dd1d01fe9fae685bb0b73516c8a3cd1c4bb7 Mon Sep 17 00:00:00 2001 From: Vladimir Kalnitsky Date: Thu, 11 Apr 2024 01:19:59 +0400 Subject: [PATCH 31/61] Assign a number --- {CIP-XXXX => CIP-0116}/README.md | 0 {CIP-XXXX => CIP-0116}/cardano-babbage.json | 0 2 files changed, 0 insertions(+), 0 deletions(-) rename {CIP-XXXX => CIP-0116}/README.md (100%) rename {CIP-XXXX => CIP-0116}/cardano-babbage.json (100%) diff --git a/CIP-XXXX/README.md b/CIP-0116/README.md similarity index 100% rename from CIP-XXXX/README.md rename to CIP-0116/README.md diff --git a/CIP-XXXX/cardano-babbage.json b/CIP-0116/cardano-babbage.json similarity index 100% rename from CIP-XXXX/cardano-babbage.json rename to CIP-0116/cardano-babbage.json From 4ab46084ccb783d58596af78ba537269b8c8bbf5 Mon Sep 17 00:00:00 2001 From: Vladimir Kalnitsky Date: Thu, 11 Apr 2024 20:43:14 +0400 Subject: [PATCH 32/61] Fix Mint type. Update docs for `Map` type schema. --- CIP-0116/README.md | 10 ++++++- CIP-0116/cardano-babbage.json | 56 +++++++++++++++++++++++++++-------- 2 files changed, 52 insertions(+), 14 deletions(-) diff --git a/CIP-0116/README.md b/CIP-0116/README.md index 0eb696792a..c7cdef15b7 100644 --- a/CIP-0116/README.md +++ b/CIP-0116/README.md @@ -64,7 +64,7 @@ Binary data MUST be encoded as lower-case hexademical strings. Restricting the c #### Encoding of mapping types -`Map`-like container types MUST be encoded as arrays of key-value pairs. Uniqueness of `"key"` objects in a map MUST be preserved (but this property is not expressible via a schema). +`Map`-like container types MUST be encoded as arrays of key-value pairs. ```json "Map": { @@ -75,13 +75,21 @@ Binary data MUST be encoded as lower-case hexademical strings. Restricting the c "key": ..., "value": ... }, + "required": [ + "key", + "value" + ], "additionalProperties": false } } ``` +Uniqueness of `"key"` objects in a map MUST be preserved (but this property is not expressible via a schema). + Implementations MUST consider mappings with conflicting keys invalid. +Some mapping-like types, specifically `Mint`, allow for duplicate keys. Types like these should not be encoded as maps, instead, `key` and `value` properties should be named differently. + #### Encoding of variant types Encoding types with variable payloads MUST be done with the use of `oneOf` and an explicit discriminator property: `tag`: diff --git a/CIP-0116/cardano-babbage.json b/CIP-0116/cardano-babbage.json index 95df810f73..afbc4581ac 100644 --- a/CIP-0116/cardano-babbage.json +++ b/CIP-0116/cardano-babbage.json @@ -35,6 +35,12 @@ "pattern": "^-?(0|[1-9][0-9]*)$", "format": "int128" }, + "NonZeroInt64": { + "title": "NonZeroInt64", + "description": "64-bit signed integer, zero excluded. Ranges: -9223372036854775808..-1 and 1..9223372036854775807", + "type": "string", + "pattern": "^-?([1-9][0-9]*)$" + }, "UInt32": { "title": "UInt32", "description": "32-bit unsigned integer", @@ -104,6 +110,12 @@ "format": "hex", "pattern": "^[0-9a-f]{56}$" }, + "AssetName": { + "title": "AssetName", + "type": "string", + "format": "hex", + "pattern": "^([0-9a-f][0-9a-f]){0,32}$" + }, "Credential": { "title": "Credential", "type": "object", @@ -1426,20 +1438,38 @@ }, "Mint": { "title": "Mint", - "description": "Minting or burning of assets. A mapping from policy IDs (script hashes) to mappings from asset names to amounts (that can be negative)", - "type": "object", - "patternProperties": { - "^[0-9a-f]{56}$": { - "type": "object", - "patternProperties": { - "^([0-9a-f][0-9a-f]){0,32}$": { - "$ref": "cardano-babbage.json#/definitions/Int64" - } + "description": "Minting or burning of assets. A mapping from policy IDs (script hashes) to mappings from asset names to amounts (that can be negative). Allows for duplicate script hash keys.", + "type": "array", + "items": { + "type": "object", + "properties": { + "script_hash": { + "$ref": "cardano-babbage.json#/definitions/ScriptHash" }, - "additionalProperties": false - } - }, - "additionalProperties": false + "assets": { + "title": "Assets", + "type": "object", + "properties": { + "key": { + "$ref": "cardano-babbage.json#/definitions/AssetName" + }, + "value": { + "$ref": "cardano-babbage.json#/definitions/NonZeroInt64" + } + }, + "required": [ + "key", + "value" + ], + "additionalProperties": false + } + }, + "required": [ + "key", + "value" + ], + "additionalProperties": false + } }, "Ed25519Signature": { "title": "Ed25519Signature", From e22fbb4490e54420703e14338fa9ebff58a92cfe Mon Sep 17 00:00:00 2001 From: Vladimir Kalnitsky Date: Thu, 18 Apr 2024 16:05:41 +0400 Subject: [PATCH 33/61] Add a link to the repo with tests --- CIP-0116/README.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/CIP-0116/README.md b/CIP-0116/README.md index c7cdef15b7..df638cf347 100644 --- a/CIP-0116/README.md +++ b/CIP-0116/README.md @@ -24,10 +24,14 @@ The full motivation text is provided in [CPS-11 | Universal JSON Encoding for Do ## Specification -This CIP is expected to contain multiple schema definitions for Cardano Eras and breaking intra-era hardforks starting from Babbage. +This CIP is expected to contain multiple json-schema definitions for Cardano Eras and breaking intra-era hardforks starting from Babbage: - [Babbage](./cardano-babbage.json) +### Tests & utilities for JSON validation + +[`cip-0116-tests`](https://github.com/mlabs-haskell/cip-0116-tests) repo contains utility functions and a test suite for the schema. In particular, there's a `mkValidatorForType` function that builds a validator function for any type defined in the schema. + ### Scope of the Schema The schemas should cover `Block` type and all of its structural components, which corresponds to the scope of CDDL files located in [the ledger repo](https://github.com/IntersectMBO/cardano-ledger/). From ec684bc6b36826dd3d87477bb22e62a037c7c65a Mon Sep 17 00:00:00 2001 From: Ryan Williams Date: Wed, 6 Mar 2024 22:54:22 -0100 Subject: [PATCH 34/61] small tidy --- CIP-0116/README.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/CIP-0116/README.md b/CIP-0116/README.md index c7cdef15b7..3bc3cad831 100644 --- a/CIP-0116/README.md +++ b/CIP-0116/README.md @@ -7,6 +7,7 @@ Authors: - Vladimir Kalnitsky Implementors: [] Discussions: + - https://github.com/cardano-foundation/CIPs/pull/742 - https://github.com/cardano-foundation/cips/pulls/766 Created: 2024-02-22 License: CC-BY-4.0 @@ -20,7 +21,7 @@ Canonical JSON encoding for Cardano domain types lets the ecosystem converge on Cardano domain types have canonical CDDL definitions (for every era), but when it comes to use in web apps, where JSON is the universally accepted format, there is no definite standard. This CIP aims to change that. -The full motivation text is provided in [CPS-11 | Universal JSON Encoding for Domain Types](https://github.com/cardano-foundation/CIPs/pull/742). +The full motivation text is provided in [CPS-11 | Universal JSON Encoding for Domain Types](https://github.com/cardano-foundation/CIPs/tree/master/CPS-0011). ## Specification @@ -259,5 +260,3 @@ It is up to implementors to decide how to serialize the values into CBOR. The pr ## Copyright This CIP is licensed under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). - -[CC-BY-4.0]: https://creativecommons.org/licenses/by/4.0/legalcode From 08e8feee70a004535a235cd88c05d6a36b7e6906 Mon Sep 17 00:00:00 2001 From: Ryan Williams Date: Wed, 6 Mar 2024 22:56:57 -0100 Subject: [PATCH 35/61] fix header link --- CIP-0116/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CIP-0116/README.md b/CIP-0116/README.md index 3bc3cad831..30d21c04d7 100644 --- a/CIP-0116/README.md +++ b/CIP-0116/README.md @@ -8,7 +8,7 @@ Authors: Implementors: [] Discussions: - https://github.com/cardano-foundation/CIPs/pull/742 - - https://github.com/cardano-foundation/cips/pulls/766 + - https://github.com/cardano-foundation/CIPs/pull/766 Created: 2024-02-22 License: CC-BY-4.0 --- From 280fd5f1968ab42a0b2ffdd646cc6cd66c5be1bd Mon Sep 17 00:00:00 2001 From: Ryan Williams Date: Thu, 7 Mar 2024 09:03:29 -0100 Subject: [PATCH 36/61] added changelog template --- CIP-0116/README.md | 17 ++++++++++++++++- CIP-0116/changelog.md | 30 ++++++++++++++++++++++++++++++ 2 files changed, 46 insertions(+), 1 deletion(-) create mode 100644 CIP-0116/changelog.md diff --git a/CIP-0116/README.md b/CIP-0116/README.md index 30d21c04d7..3ca29095dc 100644 --- a/CIP-0116/README.md +++ b/CIP-0116/README.md @@ -27,7 +27,9 @@ The full motivation text is provided in [CPS-11 | Universal JSON Encoding for Do This CIP is expected to contain multiple schema definitions for Cardano Eras and breaking intra-era hardforks starting from Babbage. -- [Babbage](./cardano-babbage.json) +| Ledger Era | Ledger Commit | Schema | Changelog Entry | +| --- | --- | --- | --- | +| Babbage | [12dc779](https://github.com/IntersectMBO/cardano-ledger/blob/12dc779d7975cbeb69c7c18c1565964a90f50920/eras/babbage/impl/cddl-files/babbage.cddl) | [cardano-babbage.json](./cardano-babbage.json) | N/A | ### Scope of the Schema @@ -244,8 +246,21 @@ Instead of providing all three variants of encoding, we base the schema on the o It is up to implementors to decide how to serialize the values into CBOR. The property we want to maintain is preserved regardless of the choice: for every block binary there is exactly one JSON encoding. +### Versioning + +This CIP should not follow a conventional versioning scheme, rather it should be altered via pull request before a hardforks to add new a JSON schema to align with new ledger design. Authors MUST follow the [Schema Scope](#scope-of-the-schema), [Schema Design Principles](#schema-design-principles) and [Schema Conventions](#schema-conventions). + +Furthermore, for each subsequent schema, the [changelog](./changelog.md) must be updated. Authors must clearly articulate the changes which has been made between the last schema and the new one being added. + ## Rationale: how does this CIP achieve its goals? +// todo + - why scope / why design principles / why conventions / why changelog + - what alternatives? + - why stick to Bech32 + - Why are addresses so tricky? + + ## Path to Active - [ ] Complete the specification diff --git a/CIP-0116/changelog.md b/CIP-0116/changelog.md new file mode 100644 index 0000000000..36be5b1e81 --- /dev/null +++ b/CIP-0116/changelog.md @@ -0,0 +1,30 @@ + +# CIP-0116 JSON Schema Changelog + +This document aims to catalog the changes between JSON schemas, to be updated as new eras are added. + +## [Babbage](./cardano-babbage.json) -> [Conway](./cardano-conway.json) (2024-xx-xx) + +- [Babbage CDDL (12dc779)](https://github.com/IntersectMBO/cardano-ledger/blob/12dc779d7975cbeb69c7c18c1565964a90f50920/eras/babbage/impl/cddl-files/babbage.cddl) +- [Conway CDDL (xxxxxxx)]() + +### Added + +### Changed + +### Removed + +### Notes + +## [Conway](./cardano-conway.json) -> xxxx (202x-xx-xx) + +- [Conway CDDL (xxxxxxx)]() +- + +### Added + +### Changed + +### Removed + +### Notes From f127bf915a7052b391ad340737c2e4497260f675 Mon Sep 17 00:00:00 2001 From: Ryan Williams Date: Thu, 7 Mar 2024 11:56:58 -0100 Subject: [PATCH 37/61] add notes to rationale --- CIP-0116/README.md | 28 ++++++++++++++++++++++++---- 1 file changed, 24 insertions(+), 4 deletions(-) diff --git a/CIP-0116/README.md b/CIP-0116/README.md index 3ca29095dc..ede1a0b789 100644 --- a/CIP-0116/README.md +++ b/CIP-0116/README.md @@ -248,17 +248,37 @@ It is up to implementors to decide how to serialize the values into CBOR. The pr ### Versioning -This CIP should not follow a conventional versioning scheme, rather it should be altered via pull request before a hardforks to add new a JSON schema to align with new ledger design. Authors MUST follow the [Schema Scope](#scope-of-the-schema), [Schema Design Principles](#schema-design-principles) and [Schema Conventions](#schema-conventions). +This CIP should not follow a conventional versioning scheme, rather it should be altered via pull request before a hardforks to add new a JSON schema to align with new ledger ers. Each schema must be standalone and not reuse definitions between eras. Authors MUST follow the [Schema Scope](#scope-of-the-schema), [Schema Design Principles](#schema-design-principles) and [Schema Conventions](#schema-conventions). Furthermore, for each subsequent schema, the [changelog](./changelog.md) must be updated. Authors must clearly articulate the changes which has been made between the last schema and the new one being added. ## Rationale: how does this CIP achieve its goals? -// todo - - why scope / why design principles / why conventions / why changelog +### Scope +- why just block data + - the most useful for most applications + - to match CDDL + +### Strictness + +This CIP lays out strong conventions that future schema authors must follow. With a large set of design principles and conventions. The aim for these is to minimize the potential for unavoidable deltas between schemas. + +By setting sometimes arbitrary conventions we hope to create a single possible interpretation from CBOR to JSON. This is beneficial as + +### JSON - what alternatives? + - JSON is by far the most useful, there really isnt any comparison. + +### Bech32 - why stick to Bech32 - - Why are addresses so tricky? + - the checksum is useful + - the prefix is also really nice + - more preferable compared to hex because + +### Versioning + - why seperate files - easier to consume and expand on + - CDDL can change between eras in ways that JSON cant be expanded to do + - easier to keep seperate ## Path to Active From b72870c68ca2b7664b8461ff992d3eb3c701b081 Mon Sep 17 00:00:00 2001 From: Ryan Williams Date: Thu, 18 Apr 2024 14:06:28 +0100 Subject: [PATCH 38/61] editorial adjustments --- CIP-0116/README.md | 37 +++++++++++++++++++------------------ CIP-0116/changelog.md | 4 ++-- 2 files changed, 21 insertions(+), 20 deletions(-) diff --git a/CIP-0116/README.md b/CIP-0116/README.md index ede1a0b789..f7346de6a2 100644 --- a/CIP-0116/README.md +++ b/CIP-0116/README.md @@ -25,11 +25,11 @@ The full motivation text is provided in [CPS-11 | Universal JSON Encoding for Do ## Specification -This CIP is expected to contain multiple schema definitions for Cardano Eras and breaking intra-era hardforks starting from Babbage. +This CIP is expected to contain multiple schema definitions for Cardano eras and breaking intra-era hardforks starting from Babbage. -| Ledger Era | Ledger Commit | Schema | Changelog Entry | -| --- | --- | --- | --- | -| Babbage | [12dc779](https://github.com/IntersectMBO/cardano-ledger/blob/12dc779d7975cbeb69c7c18c1565964a90f50920/eras/babbage/impl/cddl-files/babbage.cddl) | [cardano-babbage.json](./cardano-babbage.json) | N/A | +| Ledger era | Hardfork | Ledger Commit | Schema | Changelog Entry | +| --- | --- | --- | --- |--- | +| Babbage | Vasil | [12dc779](https://github.com/IntersectMBO/cardano-ledger/blob/12dc779d7975cbeb69c7c18c1565964a90f50920/eras/babbage/impl/cddl-files/babbage.cddl) | [cardano-babbage.json](./cardano-babbage.json) | N/A | ### Scope of the Schema @@ -49,14 +49,6 @@ For a single JSON fixture, however, there are multiple variants of encoding it a To simplify transitions of dApps between eras, the scope of changes introduced to the schemas SHOULD be limited to the scope of CDDL changes. - -#### Absence of extensibility - -The schemas MUST NOT be extensible with additional properties. This may sound counter-intuitive and against the spirit of json-schema, but there are some motivations behind that: - -- More safety from typos: object fields that are optional may be specified with slightly incorrect names in dApps' code, leading to inability of the decoders to pick up the values, which may go unnoticed. -- Clear delineation between Cardano domain types and user dApp domain types: forcing the developers to store their dApp domain data separately from Cardano data, or close to it (as opposed to mixing these together in a single object) will indirectly motivate better structured dApp code. - ### Schema Conventions These conventions help to keep the schema uniform in style. @@ -250,7 +242,7 @@ It is up to implementors to decide how to serialize the values into CBOR. The pr This CIP should not follow a conventional versioning scheme, rather it should be altered via pull request before a hardforks to add new a JSON schema to align with new ledger ers. Each schema must be standalone and not reuse definitions between eras. Authors MUST follow the [Schema Scope](#scope-of-the-schema), [Schema Design Principles](#schema-design-principles) and [Schema Conventions](#schema-conventions). -Furthermore, for each subsequent schema, the [changelog](./changelog.md) must be updated. Authors must clearly articulate the changes which has been made between the last schema and the new one being added. +Furthermore, for each subsequent schema, the [changelog](./changelog.md) must be updated. Authors must clearly articulate the deltas between schemas. ## Rationale: how does this CIP achieve its goals? @@ -265,6 +257,13 @@ This CIP lays out strong conventions that future schema authors must follow. Wit By setting sometimes arbitrary conventions we hope to create a single possible interpretation from CBOR to JSON. This is beneficial as +### Absence of extensibility + +The schemas MUST NOT be extensible with additional properties. This may sound counter-intuitive and against the spirit of json-schema, but there are some motivations behind that: + +- More safety from typos: object fields that are optional may be specified with slightly incorrect names in dApps' code, leading to inability of the decoders to pick up the values, which may go unnoticed. +- Clear delineation between Cardano domain types and user dApp domain types: forcing the developers to store their dApp domain data separately from Cardano data, or close to it (as opposed to mixing these together in a single object) will indirectly motivate better structured dApp code. + ### JSON - what alternatives? - JSON is by far the most useful, there really isnt any comparison. @@ -283,14 +282,16 @@ By setting sometimes arbitrary conventions we hope to create a single possible i ## Path to Active -- [ ] Complete the specification -- [ ] Provide an implementation of validating functions that uses this json-schema -- [ ] Collect a list of cardano domain types implementations and negotiate transition to the specified formats with maintainers (if it makes sense and is possible) - ### Acceptance Criteria +- [ ] One future ledger era schema is added +- [ ] This standard is implemented within three separate tools, libraries, etc. + ### Implementation Plan - + +- [ ] Complete the Babbage specification +- [ ] Provide an implementation of validating functions that uses this json-schema +- [ ] Collect a list of cardano domain types implementations and negotiate transition to the specified formats with maintainers (if it makes sense and is possible) ## Copyright diff --git a/CIP-0116/changelog.md b/CIP-0116/changelog.md index 36be5b1e81..4d8de75a91 100644 --- a/CIP-0116/changelog.md +++ b/CIP-0116/changelog.md @@ -3,7 +3,7 @@ This document aims to catalog the changes between JSON schemas, to be updated as new eras are added. -## [Babbage](./cardano-babbage.json) -> [Conway](./cardano-conway.json) (2024-xx-xx) +## Chang Hardfork [Babbage](./cardano-babbage.json) -> [Conway](./cardano-conway.json) (2024-xx-xx) - [Babbage CDDL (12dc779)](https://github.com/IntersectMBO/cardano-ledger/blob/12dc779d7975cbeb69c7c18c1565964a90f50920/eras/babbage/impl/cddl-files/babbage.cddl) - [Conway CDDL (xxxxxxx)]() @@ -16,7 +16,7 @@ This document aims to catalog the changes between JSON schemas, to be updated as ### Notes -## [Conway](./cardano-conway.json) -> xxxx (202x-xx-xx) +## xxxx Hardfork [Conway](./cardano-conway.json) -> xxxx (202x-xx-xx) - [Conway CDDL (xxxxxxx)]() - From 26e7a3620e88eda79c7358bacbf2a0f17783c782 Mon Sep 17 00:00:00 2001 From: Ryan Williams Date: Thu, 18 Apr 2024 15:07:50 +0100 Subject: [PATCH 39/61] flesh out rationale --- CIP-0116/README.md | 28 ++++++++++++---------------- 1 file changed, 12 insertions(+), 16 deletions(-) diff --git a/CIP-0116/README.md b/CIP-0116/README.md index f7346de6a2..ebc0032802 100644 --- a/CIP-0116/README.md +++ b/CIP-0116/README.md @@ -247,15 +247,16 @@ Furthermore, for each subsequent schema, the [changelog](./changelog.md) must be ## Rationale: how does this CIP achieve its goals? ### Scope -- why just block data - - the most useful for most applications - - to match CDDL + +We keep a lean scope, limited to the data types within Cardano blocks. The rationale for this is that block data is by far the most useful for the majority of Cardano actors. There is also one nice benefit that the definions can map directly from the provided CDDL file from ledger team. + +Defining additional would likely add unneeded overhead to the maintenance of this standard. ### Strictness This CIP lays out strong conventions that future schema authors must follow. With a large set of design principles and conventions. The aim for these is to minimize the potential for unavoidable deltas between schemas. -By setting sometimes arbitrary conventions we hope to create a single possible interpretation from CBOR to JSON. This is beneficial as +By setting sometimes arbitrary conventions we hope to create a single possible interpretation from CBOR to JSON. This is beneficial as it allows the development of downstream standards, which rely on a canonical JSON representation. ### Absence of extensibility @@ -265,20 +266,14 @@ The schemas MUST NOT be extensible with additional properties. This may sound co - Clear delineation between Cardano domain types and user dApp domain types: forcing the developers to store their dApp domain data separately from Cardano data, or close to it (as opposed to mixing these together in a single object) will indirectly motivate better structured dApp code. ### JSON - - what alternatives? - - JSON is by far the most useful, there really isnt any comparison. -### Bech32 - - why stick to Bech32 - - the checksum is useful - - the prefix is also really nice - - more preferable compared to hex because +JSON was chosen as there is no viable alternative. The majority of Cardano's web tooling is built with Javascript where JSON is the primary object representation format. -### Versioning - - why seperate files - easier to consume and expand on - - CDDL can change between eras in ways that JSON cant be expanded to do - - easier to keep seperate +Furthermore, even across non-Javascript based stacks, JSON enjoys wide tooling support, this improves the potential for builders to adopt this standard. + +### Bech32 for addresses +We choose to use Bech32 as the representation for Cardano addresses. When compared to the alternative of base64, Bech32 gives the advantages of an included checksum and a human readable prefix. These add additional safety to the standard. ## Path to Active @@ -290,7 +285,8 @@ The schemas MUST NOT be extensible with additional properties. This may sound co ### Implementation Plan - [ ] Complete the Babbage specification -- [ ] Provide an implementation of validating functions that uses this json-schema +- [x] Provide an implementation of validating functions that uses this json-schema + - [mlabs-haskell/cip-0116-tests](https://github.com/mlabs-haskell/cip-0116-tests) - [ ] Collect a list of cardano domain types implementations and negotiate transition to the specified formats with maintainers (if it makes sense and is possible) ## Copyright From bfdc224413a948990b05a66d2a94c40361aa48b6 Mon Sep 17 00:00:00 2001 From: Ryan Williams Date: Thu, 18 Apr 2024 15:55:42 +0100 Subject: [PATCH 40/61] fix typo --- CIP-0116/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CIP-0116/README.md b/CIP-0116/README.md index c2802a10ed..ed78291c07 100644 --- a/CIP-0116/README.md +++ b/CIP-0116/README.md @@ -252,7 +252,7 @@ Furthermore, for each subsequent schema, the [changelog](./changelog.md) must be ### Scope -We keep a lean scope, limited to the data types within Cardano blocks. The rationale for this is that block data is by far the most useful for the majority of Cardano actors. There is also one nice benefit that the definions can map directly from the provided CDDL file from ledger team. +We keep a lean scope, limited to the data types within Cardano blocks. The rationale for this is that block data is by far the most useful for the majority of Cardano actors. There is also one nice benefit that the definitions can map directly from the provided CDDL file from ledger team. Defining additional would likely add unneeded overhead to the maintenance of this standard. From 0c18016ed71c9a5f6fcb1229855aa332ece1a307 Mon Sep 17 00:00:00 2001 From: Ryan <44342099+Ryun1@users.noreply.github.com> Date: Fri, 19 Apr 2024 11:24:41 +0100 Subject: [PATCH 41/61] Update CIP-0116/README.md Co-authored-by: Vladimir Kalnitsky --- CIP-0116/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CIP-0116/README.md b/CIP-0116/README.md index ed78291c07..bcb8c28c11 100644 --- a/CIP-0116/README.md +++ b/CIP-0116/README.md @@ -258,7 +258,7 @@ Defining additional would likely add unneeded overhead to the maintenance of thi ### Strictness -This CIP lays out strong conventions that future schema authors must follow. With a large set of design principles and conventions. The aim for these is to minimize the potential for unavoidable deltas between schemas. +This CIP lays out strong conventions that future schema authors must follow, along with a large set of design principles and conventions. The aim is to minimize the potential for unavoidable deltas between schemas. By setting sometimes arbitrary conventions we hope to create a single possible interpretation from CBOR to JSON. This is beneficial as it allows the development of downstream standards, which rely on a canonical JSON representation. From 1c93732e8fb840c2b7a91800a572b2219692a87c Mon Sep 17 00:00:00 2001 From: Ryan <44342099+Ryun1@users.noreply.github.com> Date: Fri, 19 Apr 2024 11:24:53 +0100 Subject: [PATCH 42/61] Update CIP-0116/README.md Co-authored-by: Vladimir Kalnitsky --- CIP-0116/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CIP-0116/README.md b/CIP-0116/README.md index bcb8c28c11..3a0b730fd3 100644 --- a/CIP-0116/README.md +++ b/CIP-0116/README.md @@ -277,7 +277,7 @@ Furthermore, even across non-Javascript based stacks, JSON enjoys wide tooling s ### Bech32 for addresses -We choose to use Bech32 as the representation for Cardano addresses. When compared to the alternative of base64, Bech32 gives the advantages of an included checksum and a human readable prefix. These add additional safety to the standard. +We choose to use Bech32 as the representation for Cardano addresses. When compared to the alternative of hexademical encoding, Bech32 gives the advantages of an included checksum and a human readable prefix. ## Path to Active From e2ddb409076fb99b9290069d4fd352d0ae5226cb Mon Sep 17 00:00:00 2001 From: Ryan <44342099+Ryun1@users.noreply.github.com> Date: Fri, 19 Apr 2024 11:32:33 +0100 Subject: [PATCH 43/61] Update CIP-0116/README.md Co-authored-by: Vladimir Kalnitsky --- CIP-0116/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CIP-0116/README.md b/CIP-0116/README.md index 3a0b730fd3..2af940a0e3 100644 --- a/CIP-0116/README.md +++ b/CIP-0116/README.md @@ -289,6 +289,7 @@ We choose to use Bech32 as the representation for Cardano addresses. When compar ### Implementation Plan - [ ] Complete the Babbage specification +- [ ] Provide a test suite validating JSON fixtures for all the types against the schema - [x] Provide an implementation of validating functions that uses this json-schema - [mlabs-haskell/cip-0116-tests](https://github.com/mlabs-haskell/cip-0116-tests) - [ ] Collect a list of cardano domain types implementations and negotiate transition to the specified formats with maintainers (if it makes sense and is possible) From 865f4efdd512fcaeb720728d9b65dcd3f19da47a Mon Sep 17 00:00:00 2001 From: Ryan <44342099+Ryun1@users.noreply.github.com> Date: Fri, 19 Apr 2024 11:56:18 +0100 Subject: [PATCH 44/61] Update CIP-0116/README.md Co-authored-by: Vladimir Kalnitsky --- CIP-0116/README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/CIP-0116/README.md b/CIP-0116/README.md index 2af940a0e3..2ee7fea2e1 100644 --- a/CIP-0116/README.md +++ b/CIP-0116/README.md @@ -254,7 +254,6 @@ Furthermore, for each subsequent schema, the [changelog](./changelog.md) must be We keep a lean scope, limited to the data types within Cardano blocks. The rationale for this is that block data is by far the most useful for the majority of Cardano actors. There is also one nice benefit that the definitions can map directly from the provided CDDL file from ledger team. -Defining additional would likely add unneeded overhead to the maintenance of this standard. ### Strictness From 3960d0c6917cedd32f87ed9860c1a11484f12bb8 Mon Sep 17 00:00:00 2001 From: Ryan Williams Date: Fri, 19 Apr 2024 11:57:27 +0100 Subject: [PATCH 45/61] adjust scope rationale --- CIP-0116/README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/CIP-0116/README.md b/CIP-0116/README.md index 2ee7fea2e1..0a0b5cfd77 100644 --- a/CIP-0116/README.md +++ b/CIP-0116/README.md @@ -252,8 +252,7 @@ Furthermore, for each subsequent schema, the [changelog](./changelog.md) must be ### Scope -We keep a lean scope, limited to the data types within Cardano blocks. The rationale for this is that block data is by far the most useful for the majority of Cardano actors. There is also one nice benefit that the definitions can map directly from the provided CDDL file from ledger team. - +We keep the scope of this standard to the data types within Cardano blocks. The rationale for this is that block data is by far the most useful for the majority of Cardano actors. There is also one nice benefit that the definitions can map directly from the provided CDDL file from ledger team. ### Strictness From 7ce52f4ff7598a8dd67f5f461ced32b2593412c0 Mon Sep 17 00:00:00 2001 From: Ryan <44342099+Ryun1@users.noreply.github.com> Date: Fri, 19 Apr 2024 11:57:42 +0100 Subject: [PATCH 46/61] Update CIP-0116/README.md Co-authored-by: Vladimir Kalnitsky --- CIP-0116/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CIP-0116/README.md b/CIP-0116/README.md index 0a0b5cfd77..1085467518 100644 --- a/CIP-0116/README.md +++ b/CIP-0116/README.md @@ -258,7 +258,7 @@ We keep the scope of this standard to the data types within Cardano blocks. The This CIP lays out strong conventions that future schema authors must follow, along with a large set of design principles and conventions. The aim is to minimize the potential for unavoidable deltas between schemas. -By setting sometimes arbitrary conventions we hope to create a single possible interpretation from CBOR to JSON. This is beneficial as it allows the development of downstream standards, which rely on a canonical JSON representation. +By setting sometimes arbitrary conventions we hope to create a single possible interpretation from CBOR to JSON, alleviating any ambiguity. ### Absence of extensibility From 08e9ebbaee54ab482ed522aa2655e37083968c77 Mon Sep 17 00:00:00 2001 From: Vladimir Kalnitsky Date: Fri, 26 Apr 2024 01:56:49 +0400 Subject: [PATCH 47/61] Update cardano-babbage.json --- CIP-0116/cardano-babbage.json | 128 ++++++++++++++++++++-------------- 1 file changed, 75 insertions(+), 53 deletions(-) diff --git a/CIP-0116/cardano-babbage.json b/CIP-0116/cardano-babbage.json index afbc4581ac..5e18b55d59 100644 --- a/CIP-0116/cardano-babbage.json +++ b/CIP-0116/cardano-babbage.json @@ -7,7 +7,7 @@ "title": "BigInt", "type": "string", "description": "A long integer domain type", - "pattern": "^-?(0|[1-9][0-9]*)$", + "pattern": "^(0|-?[1-9][0-9]*)$", "examples": [ "0", "-123", @@ -25,9 +25,16 @@ "title": "UInt64", "description": "64-bit unsigned integer", "type": "string", - "pattern": "^-?(0|[1-9][0-9]*)$", + "pattern": "^(0|[1-9][0-9]*)$", "format": "uint64" }, + "PosInt64": { + "title": "PosInt64", + "description": "64-bit unsigned integer, zero-excluded. 1-18446744073709551615", + "type": "string", + "pattern": "^([1-9][0-9]*)$", + "format": "posint64" + }, "Int128": { "title": "Int128", "description": "128-bit signed integer", @@ -164,7 +171,7 @@ "type": "object", "patternProperties": { "^([0-9a-f][0-9a-f]){0,32}$": { - "$ref": "cardano-babbage.json#/definitions/UInt64" + "$ref": "cardano-babbage.json#/definitions/PosInt64" } }, "additionalProperties": false @@ -179,7 +186,7 @@ "coin": { "$ref": "cardano-babbage.json#/definitions/UInt64" }, - "multiasset": { + "assets": { "$ref": "cardano-babbage.json#/definitions/MultiAsset" } }, @@ -226,6 +233,7 @@ }, "NativeScript": { "title": "NativeScript", + "type": "object", "discriminator": { "propertyName": "tag" }, @@ -235,6 +243,7 @@ "type": "object", "properties": { "tag": { + "type": "string", "enum": [ "pubkey" ] @@ -251,6 +260,7 @@ "type": "object", "properties": { "tag": { + "type": "string", "enum": [ "all" ] @@ -270,6 +280,7 @@ "type": "object", "properties": { "tag": { + "type": "string", "enum": [ "any" ] @@ -289,6 +300,7 @@ "type": "object", "properties": { "tag": { + "type": "string", "enum": [ "n_of_k" ] @@ -311,6 +323,7 @@ "type": "object", "properties": { "tag": { + "type": "string", "enum": [ "timelock_start" ] @@ -327,6 +340,7 @@ "type": "object", "properties": { "tag": { + "type": "string", "enum": [ "timelock_expiry" ] @@ -342,6 +356,7 @@ }, "ScriptRef": { "title": "ScriptRef", + "type": "object", "discriminator": { "propertyName": "tag" }, @@ -399,6 +414,7 @@ "$ref": "cardano-babbage.json#/definitions/Value" }, "plutus_data": { + "type": "object", "discriminator": { "propertyName": "tag" }, @@ -456,6 +472,7 @@ }, "TransactionMetadatum": { "title": "TransactionMetadatum", + "type": "object", "discriminator": { "propertyName": "tag" }, @@ -479,7 +496,12 @@ "value": { "$ref": "cardano-babbage.json#/definitions/TransactionMetadatum" } - } + }, + "required": [ + "key", + "value" + ], + "additionalProperties": false } } }, @@ -528,12 +550,9 @@ ] }, "value": { - "type": "array", - "items": { - "type": "string", - "format": "hex", - "pattern": "^([0-9a-f][0-9a-f]){0,64}$" - } + "type": "string", + "format": "hex", + "pattern": "^([0-9a-f][0-9a-f]){0,64}$" } }, "required": [ "tag", "value" ], @@ -551,7 +570,8 @@ }, "value": { "type": "string", - "maxLength": 64 + "maxLength": 64, + "format": "string64" } }, "required": [ "tag", "value" ], @@ -565,8 +585,8 @@ "items": { "$ref": "cardano-babbage.json#/definitions/Int128" }, - "maxLength": 166, - "minLength": 166 + "maxItems": 166, + "minItems": 166 }, "PlutusV2CostModel": { "title": "PlutusV2CostModel", @@ -574,8 +594,8 @@ "items": { "$ref": "cardano-babbage.json#/definitions/Int128" }, - "maxLength": 175, - "minLength": 175 + "maxItems": 175, + "minItems": 175 }, "CostModels": { "title": "CostModels", @@ -603,24 +623,9 @@ } }, "additionalProperties": false, - "required": [ "mem_price", "step_price" ] - }, - "Nonce": { - "title": "Nonce", - "oneOf": [ - { - "title": "Identity Nonce", - "type": "string", - "enum": [ - "" - ] - }, - { - "title": "Nonce from hash", - "type": "string", - "format": "hex", - "pattern": "^[0-9a-f]{64}$" - } + "required": [ + "mem_price", + "step_price" ] }, "ExUnits": { @@ -673,9 +678,6 @@ "expansion_rate": { "$ref": "cardano-babbage.json#/definitions/UnitInterval" }, - "extra_entropy": { - "$ref": "cardano-babbage.json#/definitions/Nonce" - }, "key_deposit": { "$ref": "cardano-babbage.json#/definitions/UInt64" }, @@ -713,7 +715,7 @@ "$ref": "cardano-babbage.json#/definitions/UInt64" }, "n_opt": { - "$ref": "cardano-babbage.json#/definitions/Int128" + "$ref": "cardano-babbage.json#/definitions/UInt64" }, "pool_deposit": { "$ref": "cardano-babbage.json#/definitions/UInt64" @@ -747,7 +749,8 @@ "title": "ProtocolParamUpdate for a given GenesisHash", "$ref": "cardano-babbage.json#/definitions/ProtocolParamUpdate" } - } + }, + "additionalProperties": false } }, "required": [ @@ -924,6 +927,7 @@ }, "PlutusData": { "title": "PlutusData", + "type": "object", "discriminator": { "propertyName": "tag" }, @@ -1051,10 +1055,12 @@ "DNSName": { "title": "DNSName", "type": "string", - "maxLength": 64 + "maxLength": 64, + "format": "string64" }, "Relay": { "title": "Relay", + "type": "object", "discriminator": { "propertyName": "tag" }, @@ -1070,7 +1076,7 @@ }, "port": { "type": "integer", - "maxValue": 65535 + "maximum": 65535 }, "ipv4": { "$ref": "cardano-babbage.json#/definitions/Ipv4" @@ -1095,15 +1101,17 @@ }, "port": { "type": "integer", - "maxValue": 65535 + "minimum": 1, + "maximum": 65535 }, - "dnsName": { + "dns_name": { "$ref": "cardano-babbage.json#/definitions/DNSName" } }, "additionalProperties": false, "required": [ - "tag" + "tag", + "dns_name" ] }, { @@ -1115,13 +1123,14 @@ "multi_host_name" ] }, - "dnsName": { + "dns_name": { "$ref": "cardano-babbage.json#/definitions/DNSName" } }, "additionalProperties": false, "required": [ - "tag" + "tag", + "dns_name" ] } ] @@ -1130,13 +1139,15 @@ "title": "VRFKeyHash", "type": "string", "description": "blake2b_256 digest of a VRF verification key, encoded as bech32", - "pattern": "^vrf_vkh[02-9ac-hj-np-z]*" + "pattern": "^vrf_vkh[02-9ac-hj-np-z]*", + "format": "bech32" }, "URL": { "title": "URL", "description": "UTF-8 URL string. Maximum size is 64 bytes, but there is no way to express byte length limit in a json-schema (maxLength limits the number of characters)", "type": "string", - "maxLength": 64 + "maxLength": 64, + "format": "string64" }, "PoolMetadata": { "title": "PoolMetadata", @@ -1145,7 +1156,7 @@ "url": { "$ref": "cardano-babbage.json#/definitions/URL" }, - "pool_metadata_hash": { + "hash": { "title": "Pool Metadata Hash", "type": "string", "format": "hex", @@ -1153,14 +1164,23 @@ } }, "additionalProperties": false, - "required": ["url", "pool_metadata_hash"] + "required": [ + "url", + "hash" + ] + }, + "PoolPubKeyHash": { + "title": "PoolPubKeyHash", + "type": "string", + "format": "bech32", + "pattern": "^(pool1)[02-9ac-hj-np-z]*$" }, "PoolParams": { "title": "PoolParams", "type": "object", "properties": { "operator": { - "$ref": "cardano-babbage.json#/definitions/Ed25519KeyHash" + "$ref": "cardano-babbage.json#/definitions/PoolPubKeyHash" }, "vrf_keyhash": { "$ref": "cardano-babbage.json#/definitions/VRFKeyHash" @@ -1226,6 +1246,7 @@ }, "MoveInstantaneousRewards": { "title": "MoveInstantaneousRewards", + "type": "object", "discriminator": { "propertyName": "tag" }, @@ -1296,6 +1317,7 @@ }, "Certificate": { "title": "Certificate", + "type": "object", "discriminator": { "propertyName": "tag" }, @@ -1341,7 +1363,7 @@ "stake_delegation" ] }, - "stake_credential": { + "credential": { "$ref": "cardano-babbage.json#/definitions/Credential" }, "pool_keyhash": { @@ -1378,7 +1400,7 @@ ] }, "pool_keyhash": { - "$ref": "cardano-babbage.json#/definitions/Ed25519KeyHash" + "$ref": "cardano-babbage.json#/definitions/PoolPubKeyHash" }, "epoch": { "$ref": "cardano-babbage.json#/definitions/UInt32" From 4b042df9d92d67a81f9cf14d6dfd66019aad6711 Mon Sep 17 00:00:00 2001 From: Vladimir Kalnitsky Date: Fri, 26 Apr 2024 01:57:44 +0400 Subject: [PATCH 48/61] Format --- CIP-0116/cardano-babbage.json | 190 +++++++++++++++++++++++++++------- 1 file changed, 154 insertions(+), 36 deletions(-) diff --git a/CIP-0116/cardano-babbage.json b/CIP-0116/cardano-babbage.json index 5e18b55d59..d0f8d5e620 100644 --- a/CIP-0116/cardano-babbage.json +++ b/CIP-0116/cardano-babbage.json @@ -142,7 +142,10 @@ "$ref": "cardano-babbage.json#/definitions/Ed25519KeyHash" } }, - "required": ["tag", "value"], + "required": [ + "tag", + "value" + ], "additionalProperties": false }, { @@ -157,7 +160,10 @@ "$ref": "cardano-babbage.json#/definitions/ScriptHash" } }, - "required": ["tag", "value"], + "required": [ + "tag", + "value" + ], "additionalProperties": false } ] @@ -190,7 +196,9 @@ "$ref": "cardano-babbage.json#/definitions/MultiAsset" } }, - "required": ["coin"], + "required": [ + "coin" + ], "additionalProperties": false }, "TransactionHash": { @@ -212,7 +220,10 @@ "$ref": "cardano-babbage.json#/definitions/UInt32" } }, - "required": ["transaction_id", "index"], + "required": [ + "transaction_id", + "index" + ], "additionalProperties": false }, "PlutusScript": { @@ -228,7 +239,10 @@ "pattern": "^([0-9a-f][0-9a-f])+$" } }, - "required": ["language", "bytes"], + "required": [ + "language", + "bytes" + ], "additionalProperties": false }, "NativeScript": { @@ -253,7 +267,10 @@ } }, "additionalProperties": false, - "required": ["tag", "pubkey"] + "required": [ + "tag", + "pubkey" + ] }, { "title": "ScriptAll", @@ -273,7 +290,10 @@ } }, "additionalProperties": false, - "required": ["tag", "scripts"] + "required": [ + "tag", + "scripts" + ] }, { "title": "ScriptAny", @@ -293,7 +313,10 @@ } }, "additionalProperties": false, - "required": ["tag", "scripts"] + "required": [ + "tag", + "scripts" + ] }, { "title": "ScriptNOfK", @@ -316,7 +339,11 @@ } }, "additionalProperties": false, - "required": [ "tag", "scripts", "n" ] + "required": [ + "tag", + "scripts", + "n" + ] }, { "title": "TimelockStart", @@ -333,7 +360,10 @@ } }, "additionalProperties": false, - "required": [ "tag", "slot" ] + "required": [ + "tag", + "slot" + ] }, { "title": "TimelockExpiry", @@ -350,7 +380,10 @@ } }, "additionalProperties": false, - "required": [ "tag", "slot" ] + "required": [ + "tag", + "slot" + ] } ] }, @@ -375,7 +408,10 @@ "$ref": "cardano-babbage.json#/definitions/PlutusScript" } }, - "required": ["tag", "value"], + "required": [ + "tag", + "value" + ], "additionalProperties": false }, { @@ -392,7 +428,10 @@ "$ref": "cardano-babbage.json#/definitions/NativeScript" } }, - "required": ["tag", "value"], + "required": [ + "tag", + "value" + ], "additionalProperties": false } ] @@ -467,7 +506,10 @@ "$ref": "cardano-babbage.json#/definitions/TransactionOutput" } }, - "required": ["input", "output"], + "required": [ + "input", + "output" + ], "additionalProperties": false }, "TransactionMetadatum": { @@ -505,7 +547,10 @@ } } }, - "required": [ "tag", "contents" ], + "required": [ + "tag", + "contents" + ], "additionalProperties": false }, { @@ -523,7 +568,10 @@ } } }, - "required": [ "tag", "contents" ], + "required": [ + "tag", + "contents" + ], "additionalProperties": false }, { @@ -538,7 +586,10 @@ "$ref": "cardano-babbage.json#/definitions/Int128" } }, - "required": [ "tag", "value" ], + "required": [ + "tag", + "value" + ], "additionalProperties": false }, { @@ -555,7 +606,10 @@ "pattern": "^([0-9a-f][0-9a-f]){0,64}$" } }, - "required": [ "tag", "value" ], + "required": [ + "tag", + "value" + ], "additionalProperties": false }, { @@ -574,7 +628,10 @@ "format": "string64" } }, - "required": [ "tag", "value" ], + "required": [ + "tag", + "value" + ], "additionalProperties": false } ] @@ -639,7 +696,10 @@ "$ref": "cardano-babbage.json#/definitions/UInt64" } }, - "required": [ "mem", "steps" ], + "required": [ + "mem", + "steps" + ], "additionalProperties": false }, "ProtocolVersion": { @@ -653,7 +713,10 @@ "$ref": "cardano-babbage.json#/definitions/UInt32" } }, - "required": [ "major", "minor" ], + "required": [ + "major", + "minor" + ], "additionalProperties": false }, "ProtocolParamUpdate": { @@ -1335,7 +1398,10 @@ "$ref": "cardano-babbage.json#/definitions/Credential" } }, - "required": ["tag", "credential"], + "required": [ + "tag", + "credential" + ], "additionalProperties": false }, { @@ -1351,7 +1417,10 @@ "$ref": "cardano-babbage.json#/definitions/Credential" } }, - "required": ["tag", "credential"], + "required": [ + "tag", + "credential" + ], "additionalProperties": false }, { @@ -1370,7 +1439,11 @@ "$ref": "cardano-babbage.json#/definitions/Ed25519KeyHash" } }, - "required": ["tag", "stake_credential", "pool_keyhash"], + "required": [ + "tag", + "stake_credential", + "pool_keyhash" + ], "additionalProperties": false }, { @@ -1386,7 +1459,10 @@ "$ref": "cardano-babbage.json#/definitions/PoolParams" } }, - "required": ["tag", "pool_params"], + "required": [ + "tag", + "pool_params" + ], "additionalProperties": false }, { @@ -1406,7 +1482,11 @@ "$ref": "cardano-babbage.json#/definitions/UInt32" } }, - "required": ["tag", "pool_keyhash", "epoch"], + "required": [ + "tag", + "pool_keyhash", + "epoch" + ], "additionalProperties": false }, { @@ -1429,7 +1509,12 @@ "$ref": "cardano-babbage.json#/definitions/VRFKeyHash" } }, - "required": ["tag", "genesis_hash", "genesis_delegate_hash", "vrf_keyhash"], + "required": [ + "tag", + "genesis_hash", + "genesis_delegate_hash", + "vrf_keyhash" + ], "additionalProperties": false }, { @@ -1445,7 +1530,10 @@ "$ref": "cardano-babbage.json#/definitions/MoveInstantaneousRewards" } }, - "required": ["tag", "move_instantaneous_rewards"], + "required": [ + "tag", + "move_instantaneous_rewards" + ], "additionalProperties": false } ] @@ -1561,7 +1649,12 @@ "$ref": "cardano-babbage.json#/definitions/ExUnits" } }, - "required": ["data", "tag", "index", "ex_units"], + "required": [ + "data", + "tag", + "index", + "ex_units" + ], "additionalProperties": false }, "Vkeywitness": { @@ -1575,7 +1668,10 @@ "$ref": "cardano-babbage.json#/definitions/Ed25519Signature" } }, - "required": ["vkey", "signature"], + "required": [ + "vkey", + "signature" + ], "additionalProperties": false }, "TransactionWitnessSet": { @@ -1644,7 +1740,11 @@ "$ref": "cardano-babbage.json#/definitions/TransactionWitnessSet" } }, - "required": ["body", "is_valid", "witness_set"], + "required": [ + "body", + "is_valid", + "witness_set" + ], "additionalProperties": false }, "AuxiliaryDataSet": { @@ -1669,7 +1769,10 @@ "$ref": "cardano-babbage.json#/definitions/ByteString" } }, - "required": ["output", "proof"], + "required": [ + "output", + "proof" + ], "additionalProperties": false }, "HeaderLeaderCert": { @@ -1694,7 +1797,11 @@ "$ref": "cardano-babbage.json#/definitions/VRFCert" } }, - "required": ["tag", "nonce", "leader"], + "required": [ + "tag", + "nonce", + "leader" + ], "additionalProperties": false }, { @@ -1709,7 +1816,10 @@ "$ref": "cardano-babbage.json#/definitions/VRFCert" } }, - "required": ["tag", "cert"], + "required": [ + "tag", + "cert" + ], "additionalProperties": false } ] @@ -1763,7 +1873,12 @@ "$ref": "cardano-babbage.json#/definitions/Ed25519Signature" } }, - "required": ["hot_vkey", "kes_period", "sequence_number", "sigma"], + "required": [ + "hot_vkey", + "kes_period", + "sequence_number", + "sigma" + ], "additionalProperties": false }, "HeaderBody": { @@ -1825,7 +1940,10 @@ "$ref": "cardano-babbage.json#/definitions/HeaderBody" } }, - "required": [ "body_signature", "header_body" ], + "required": [ + "body_signature", + "header_body" + ], "additionalProperties": false }, "Block": { From caadc7c8f0cbf5596cc99cc9cda483bfed1e3d19 Mon Sep 17 00:00:00 2001 From: Vladimir Kalnitsky Date: Fri, 26 Apr 2024 01:59:19 +0400 Subject: [PATCH 49/61] Fix incorrectly specified required field --- CIP-0116/cardano-babbage.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CIP-0116/cardano-babbage.json b/CIP-0116/cardano-babbage.json index d0f8d5e620..1409ac4647 100644 --- a/CIP-0116/cardano-babbage.json +++ b/CIP-0116/cardano-babbage.json @@ -1441,7 +1441,7 @@ }, "required": [ "tag", - "stake_credential", + "credential", "pool_keyhash" ], "additionalProperties": false From 987aa2852c2812318c87cbb5124e0a057a2b4378 Mon Sep 17 00:00:00 2001 From: Vladimir Kalnitsky Date: Fri, 26 Apr 2024 02:00:56 +0400 Subject: [PATCH 50/61] Fix incorrectly specified required Mint properties --- CIP-0116/cardano-babbage.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CIP-0116/cardano-babbage.json b/CIP-0116/cardano-babbage.json index 1409ac4647..7356b94905 100644 --- a/CIP-0116/cardano-babbage.json +++ b/CIP-0116/cardano-babbage.json @@ -1575,8 +1575,8 @@ } }, "required": [ - "key", - "value" + "script_hash", + "assets" ], "additionalProperties": false } From 144e049ea556f09760c9560b93173e5e0e0de525 Mon Sep 17 00:00:00 2001 From: Vladimir Kalnitsky Date: Fri, 26 Apr 2024 02:09:52 +0400 Subject: [PATCH 51/61] Add missing Array wrapper for Mint assets --- CIP-0116/cardano-babbage.json | 31 +++++++++++++++++-------------- 1 file changed, 17 insertions(+), 14 deletions(-) diff --git a/CIP-0116/cardano-babbage.json b/CIP-0116/cardano-babbage.json index 7356b94905..76325aafea 100644 --- a/CIP-0116/cardano-babbage.json +++ b/CIP-0116/cardano-babbage.json @@ -1557,21 +1557,24 @@ "$ref": "cardano-babbage.json#/definitions/ScriptHash" }, "assets": { - "title": "Assets", - "type": "object", - "properties": { - "key": { - "$ref": "cardano-babbage.json#/definitions/AssetName" + "type": "array", + "items": { + "title": "Assets", + "type": "object", + "properties": { + "asset_name": { + "$ref": "cardano-babbage.json#/definitions/AssetName" + }, + "amount": { + "$ref": "cardano-babbage.json#/definitions/NonZeroInt64" + } }, - "value": { - "$ref": "cardano-babbage.json#/definitions/NonZeroInt64" - } - }, - "required": [ - "key", - "value" - ], - "additionalProperties": false + "required": [ + "asset_name", + "amount" + ], + "additionalProperties": false + } } }, "required": [ From eab98df994cfc15b4a59c072f9829d33a5e0c7e5 Mon Sep 17 00:00:00 2001 From: Vladimir Kalnitsky Date: Fri, 26 Apr 2024 21:12:56 +0400 Subject: [PATCH 52/61] Add new formats --- CIP-0116/README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CIP-0116/README.md b/CIP-0116/README.md index df638cf347..91f261907c 100644 --- a/CIP-0116/README.md +++ b/CIP-0116/README.md @@ -179,6 +179,10 @@ Some non-standard `format` types are used: - `hex` - lower-case hex-encoded byte string - `bech32` - [bech32](https://en.bitcoin.it/wiki/Bech32) string - `base58` - [base58](https://bitcoinwiki.org/wiki/base58) string +- `uint64` - 64-bit unsigned integer +- `int128` - 128-bit signed integer +- `string64` - a unicode string that must not exceed 64 bytes when utf8-encoded. +- `posint64` - a positive (0 excluded) 64-bit integer. `1 .. 2^64-1` ### Limitations From cdc6b6b35a48ca0fa93f982567be8086e88c2b91 Mon Sep 17 00:00:00 2001 From: Vladimir Kalnitsky Date: Fri, 26 Apr 2024 22:12:26 +0400 Subject: [PATCH 53/61] Specify length for BootstrapWitness chain_code --- CIP-0116/cardano-babbage.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CIP-0116/cardano-babbage.json b/CIP-0116/cardano-babbage.json index 76325aafea..9e07533d05 100644 --- a/CIP-0116/cardano-babbage.json +++ b/CIP-0116/cardano-babbage.json @@ -1608,7 +1608,7 @@ "chain_code": { "type": "string", "format": "hex", - "pattern": "^([0-9a-f][0-9a-f])*$" + "pattern": "^([0-9a-f][0-9a-f]){32}$" }, "signature": { "$ref": "cardano-babbage.json#/definitions/Ed25519Signature" From 16c9e4d9d4c061cd6018e3556573b0cfe0ec402d Mon Sep 17 00:00:00 2001 From: Vladimir Kalnitsky Date: Mon, 29 Apr 2024 19:36:01 +0400 Subject: [PATCH 54/61] Move PoolMetadataHash to a separate type --- CIP-0116/cardano-babbage.json | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/CIP-0116/cardano-babbage.json b/CIP-0116/cardano-babbage.json index 9e07533d05..dbb9730915 100644 --- a/CIP-0116/cardano-babbage.json +++ b/CIP-0116/cardano-babbage.json @@ -1212,6 +1212,13 @@ "maxLength": 64, "format": "string64" }, + "PoolMetadataHash": { + "title": "PoolMetadataHash", + "description": "Pool Metadata Hash", + "type": "string", + "format": "hex", + "pattern": "^[0-9a-f]{64}$" + }, "PoolMetadata": { "title": "PoolMetadata", "type": "object", @@ -1220,10 +1227,7 @@ "$ref": "cardano-babbage.json#/definitions/URL" }, "hash": { - "title": "Pool Metadata Hash", - "type": "string", - "format": "hex", - "pattern": "^[0-9a-f]{64}$" + "$ref": "cardano-babbage.json#/definitions/PoolMetadataHash" } }, "additionalProperties": false, From c0814112e2ecdb61152fa55378b465c94c17dc0d Mon Sep 17 00:00:00 2001 From: Vladimir Kalnitsky Date: Mon, 29 Apr 2024 19:36:42 +0400 Subject: [PATCH 55/61] Specify VRFCert proof length --- CIP-0116/cardano-babbage.json | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/CIP-0116/cardano-babbage.json b/CIP-0116/cardano-babbage.json index dbb9730915..eb6b56a052 100644 --- a/CIP-0116/cardano-babbage.json +++ b/CIP-0116/cardano-babbage.json @@ -1773,7 +1773,9 @@ "$ref": "cardano-babbage.json#/definitions/ByteString" }, "proof": { - "$ref": "cardano-babbage.json#/definitions/ByteString" + "$ref": "cardano-babbage.json#/definitions/ByteString", + "type": "string", + "pattern": "^[0-9a-f]{160}$" } }, "required": [ From 89736cf03448a15e156917e3244e418827a0c21c Mon Sep 17 00:00:00 2001 From: Vladimir Kalnitsky Date: Mon, 29 Apr 2024 19:37:01 +0400 Subject: [PATCH 56/61] Remove legacy HeaderLeaderCert --- CIP-0116/cardano-babbage.json | 95 +++++++++-------------------------- 1 file changed, 23 insertions(+), 72 deletions(-) diff --git a/CIP-0116/cardano-babbage.json b/CIP-0116/cardano-babbage.json index eb6b56a052..7d3917b6b1 100644 --- a/CIP-0116/cardano-babbage.json +++ b/CIP-0116/cardano-babbage.json @@ -1784,55 +1784,6 @@ ], "additionalProperties": false }, - "HeaderLeaderCert": { - "title": "HeaderLeaderCert", - "type": "object", - "discriminator": { - "propertyName": "tag" - }, - "oneOf": [ - { - "type": "object", - "properties": { - "tag": { - "enum": [ - "nonce_and_leader" - ] - }, - "nonce": { - "$ref": "cardano-babbage.json#/definitions/VRFCert" - }, - "leader": { - "$ref": "cardano-babbage.json#/definitions/VRFCert" - } - }, - "required": [ - "tag", - "nonce", - "leader" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "tag": { - "enum": [ - "vrf_result" - ] - }, - "cert": { - "$ref": "cardano-babbage.json#/definitions/VRFCert" - } - }, - "required": [ - "tag", - "cert" - ], - "additionalProperties": false - } - ] - }, "KESVKey": { "title": "KESVKey", "type": "string", @@ -1894,48 +1845,48 @@ "title": "HeaderBody", "type": "object", "properties": { - "block_body_hash": { - "$ref": "cardano-babbage.json#/definitions/BlockHash" - }, - "block_body_size": { - "$ref": "cardano-babbage.json#/definitions/UInt32" - }, "block_number": { "$ref": "cardano-babbage.json#/definitions/UInt32" }, + "slot": { + "$ref": "cardano-babbage.json#/definitions/UInt64" + }, + "prev_hash": { + "$ref": "cardano-babbage.json#/definitions/BlockHash" + }, "issuer_vkey": { "$ref": "cardano-babbage.json#/definitions/Ed25519PublicKey" }, - "leader_cert": { - "$ref": "cardano-babbage.json#/definitions/HeaderLeaderCert" + "vrf_vkey": { + "$ref": "cardano-babbage.json#/definitions/VRFVKey" }, - "operational_cert": { - "$ref": "cardano-babbage.json#/definitions/OperationalCert" + "vrf_result": { + "$ref": "cardano-babbage.json#/definitions/VRFCert" }, - "prev_hash": { + "block_body_size": { + "$ref": "cardano-babbage.json#/definitions/UInt32" + }, + "block_body_hash": { "$ref": "cardano-babbage.json#/definitions/BlockHash" }, + "operational_cert": { + "$ref": "cardano-babbage.json#/definitions/OperationalCert" + }, "protocol_version": { "$ref": "cardano-babbage.json#/definitions/ProtocolVersion" - }, - "slot": { - "$ref": "cardano-babbage.json#/definitions/UInt64" - }, - "vrf_vkey": { - "$ref": "cardano-babbage.json#/definitions/VRFVKey" } }, "additionalProperties": false, "required": [ - "block_body_hash", - "block_body_size", "block_number", + "slot", "issuer_vkey", - "leader_cert", + "vrf_vkey", + "vrf_result", + "block_body_size", + "block_body_hash", "operational_cert", - "protocol_version", - "slot", - "vrf_vkey" + "protocol_version" ] }, "Header": { From cc391f2cae0013fd1a61ffd5142fad8306aaf41f Mon Sep 17 00:00:00 2001 From: Vladimir Kalnitsky Date: Mon, 29 Apr 2024 20:15:21 +0400 Subject: [PATCH 57/61] Inline AuxiliaryDataSet type --- CIP-0116/cardano-babbage.json | 21 +++++++++------------ 1 file changed, 9 insertions(+), 12 deletions(-) diff --git a/CIP-0116/cardano-babbage.json b/CIP-0116/cardano-babbage.json index 7d3917b6b1..af67c8877a 100644 --- a/CIP-0116/cardano-babbage.json +++ b/CIP-0116/cardano-babbage.json @@ -1754,17 +1754,6 @@ ], "additionalProperties": false }, - "AuxiliaryDataSet": { - "type": "object", - "title": "AuxiliaryDataSet", - "description": "A mapping from numbers to AuxiliaryData", - "patternProperties": { - "^(0|[1-9][0-9]*)$": { - "$ref": "cardano-babbage.json#/definitions/AuxiliaryData" - } - }, - "additionalProperties": false - }, "VRFCert": { "title": "VRFCert", "type": "object", @@ -1911,7 +1900,15 @@ "type": "object", "properties": { "auxiliary_data_set": { - "$ref": "cardano-babbage.json#/definitions/AuxiliaryDataSet" + "type": "object", + "title": "AuxiliaryDataSet", + "description": "A mapping from transaction indices to AuxiliaryData values", + "patternProperties": { + "^(0|[1-9][0-9]*)$": { + "$ref": "cardano-babbage.json#/definitions/AuxiliaryData" + } + }, + "additionalProperties": false }, "header": { "$ref": "cardano-babbage.json#/definitions/Header" From 820350ba376a24e1b3122051b42349b6127cc115 Mon Sep 17 00:00:00 2001 From: Vladimir Kalnitsky Date: Mon, 29 Apr 2024 22:09:07 +0400 Subject: [PATCH 58/61] Update 'Path to active' --- CIP-0116/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CIP-0116/README.md b/CIP-0116/README.md index 91f261907c..3818cd32a8 100644 --- a/CIP-0116/README.md +++ b/CIP-0116/README.md @@ -255,8 +255,8 @@ It is up to implementors to decide how to serialize the values into CBOR. The pr ## Path to Active -- [ ] Complete the specification -- [ ] Provide an implementation of validating functions that uses this json-schema +- [x] Complete the specification for the current era +- [x] Provide [an implementation](https://github.com/mlabs-haskell/cip-0116-tests) of validating functions that uses this json-schema - [ ] Collect a list of cardano domain types implementations and negotiate transition to the specified formats with maintainers (if it makes sense and is possible) ### Acceptance Criteria From 71593aabc1409ca0ff6a12586ebbb67a464b41c9 Mon Sep 17 00:00:00 2001 From: Ryan <44342099+Ryun1@users.noreply.github.com> Date: Fri, 3 May 2024 18:24:31 +0100 Subject: [PATCH 59/61] Update CIP-0116/README.md Co-authored-by: Vladimir Kalnitsky --- CIP-0116/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CIP-0116/README.md b/CIP-0116/README.md index 8c7547fef1..0672a91921 100644 --- a/CIP-0116/README.md +++ b/CIP-0116/README.md @@ -260,7 +260,7 @@ We keep the scope of this standard to the data types within Cardano blocks. The ### Strictness -This CIP lays out strong conventions that future schema authors must follow, along with a large set of design principles and conventions. The aim is to minimize the potential for unavoidable deltas between schemas. +This CIP lays out strong conventions that future schema authors must follow, along with a large set of design principles. The aim is to minimize the potential for unavoidable deltas between schemas. By setting sometimes arbitrary conventions we hope to create a single possible interpretation from CBOR to JSON, alleviating any ambiguity. From d11978acffda6db5efc4a40800ea73c600bd9d06 Mon Sep 17 00:00:00 2001 From: Vladimir Kalnitsky Date: Fri, 3 May 2024 20:27:28 +0300 Subject: [PATCH 60/61] Add myself to implementors Co-authored-by: Ryan <44342099+Ryun1@users.noreply.github.com> --- CIP-0116/README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CIP-0116/README.md b/CIP-0116/README.md index 3818cd32a8..4eb48112f1 100644 --- a/CIP-0116/README.md +++ b/CIP-0116/README.md @@ -5,7 +5,8 @@ Category: Tools Status: Proposed Authors: - Vladimir Kalnitsky -Implementors: [] +Implementors: + - Vladimir Kalnitsky Discussions: - https://github.com/cardano-foundation/cips/pulls/766 Created: 2024-02-22 From 15fc23aa225030b0a1462e79564c4c174f58b426 Mon Sep 17 00:00:00 2001 From: Vladimir Kalnitsky Date: Fri, 3 May 2024 21:41:08 +0400 Subject: [PATCH 61/61] Use PoolPubKeyHash instead of Ed25519KeyHash in stake delegation cert --- CIP-0116/cardano-babbage.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CIP-0116/cardano-babbage.json b/CIP-0116/cardano-babbage.json index af67c8877a..edc6bbdf15 100644 --- a/CIP-0116/cardano-babbage.json +++ b/CIP-0116/cardano-babbage.json @@ -1440,7 +1440,7 @@ "$ref": "cardano-babbage.json#/definitions/Credential" }, "pool_keyhash": { - "$ref": "cardano-babbage.json#/definitions/Ed25519KeyHash" + "$ref": "cardano-babbage.json#/definitions/PoolPubKeyHash" } }, "required": [