From 38bf5e42082241a1003e2e33ca8feb425f394bd4 Mon Sep 17 00:00:00 2001 From: Kammerlo Date: Mon, 17 Mar 2025 14:15:36 +0100 Subject: [PATCH 01/31] Adding 1517 metadata label to registry for Reeve - transparent and verifiable financial records on-chain --- CIP-0010/registry.json | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CIP-0010/registry.json b/CIP-0010/registry.json index e444b63ec9..21f7f33afe 100644 --- a/CIP-0010/registry.json +++ b/CIP-0010/registry.json @@ -59,6 +59,10 @@ "transaction_metadatum_label": 1304, "description": "on-chain certification metadata" }, + { + "transaction_metadatum_label": 1517, + "description": "Reeve - transparent and verifiable financial records on-chain" + }, { "transaction_metadatum_label": 1564, "description": "Marlowe - a DSL for writing and executing financial contracts" From 912e6a2660251e9909cd254d62fdcd8a8de3a95e Mon Sep 17 00:00:00 2001 From: Kammerlo Date: Tue, 8 Jul 2025 11:06:10 +0200 Subject: [PATCH 02/31] docs: changing the metadata label for reeve after the official launch --- CIP-0010/registry.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CIP-0010/registry.json b/CIP-0010/registry.json index b38c86164a..b3a2f32b5b 100644 --- a/CIP-0010/registry.json +++ b/CIP-0010/registry.json @@ -60,7 +60,7 @@ "description": "on-chain certification metadata" }, { - "transaction_metadatum_label": 1517, + "transaction_metadatum_label": 1447, "description": "Reeve - transparent and verifiable financial records on-chain" }, { From 3c66f108ad53622bcd930f1363ea5a52857df821 Mon Sep 17 00:00:00 2001 From: Kammerlo Date: Wed, 9 Jul 2025 08:27:02 +0200 Subject: [PATCH 03/31] docs: adding reeve soft launch metadata back --- CIP-0010/registry.json | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CIP-0010/registry.json b/CIP-0010/registry.json index b3a2f32b5b..3d421a6f06 100644 --- a/CIP-0010/registry.json +++ b/CIP-0010/registry.json @@ -63,6 +63,10 @@ "transaction_metadatum_label": 1447, "description": "Reeve - transparent and verifiable financial records on-chain" }, + { + "transaction_metadatum_label": 1517, + "description": "Reeve - obsolete - pre-launch metadata" + }, { "transaction_metadatum_label": 1564, "description": "Marlowe - a DSL for writing and executing financial contracts" From 03c9ea45d315491ea6bf34d444aa16b202f2bf7c Mon Sep 17 00:00:00 2001 From: Kammerlo Date: Thu, 17 Jul 2025 09:52:45 +0200 Subject: [PATCH 04/31] docs: first version of CIP 1447 to start receiving feedback --- CIP-1447/README.md | 176 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 176 insertions(+) create mode 100644 CIP-1447/README.md diff --git a/CIP-1447/README.md b/CIP-1447/README.md new file mode 100644 index 0000000000..bd792caf51 --- /dev/null +++ b/CIP-1447/README.md @@ -0,0 +1,176 @@ +--- +CIP: 1447 +Title: On-chain financial transactions +Category: Metadata +Status: Proposed +Authors: + - Thomas Kammerlocher +Implementors: + - Reeve: https://github.com/cardano-foundation/cf-reeve-platform +Discussions: + - +Created: 2025-07-17 +License: CC-BY-4.0 +--- + +# Abstract + +The need for transparency of organisations and legal entities continues to grow as a cornerstone of trust. This demand especially includes the need for transparency of financial transactions of these entities to prove they are fulfilling their purpose. + +This Cardano Improvement Proposal (CIP) introduces a standardized method for anchoring both single financial transactions and custom organisational reports into transaction metadata, leveraging the blockchain as an immutable and publicly verifiable layer of trust. +The proposed standard is designed to be easily intelligible, allowing auditors, stakeholders, and the public to both trace individual transactions and analyze aggregated custom reports, creating a holistic and unalterable financial picture for any entity. +To ensure its long-term viability and adoption, the CIP also outlines a self-sustaining model to support ongoing development and maintenance of the standard, establishing Cardano as the premier infrastructure for organisational financial accountability. + +# Motivation: Why this CIP is necessary? + +True transparency is achieved not by merely publishing data, but by ensuring it is structured in a way that is universally understandable and interpretable for everyone. +Without a common standard, on-chain financial data remains cryptic to most, failing to build the trust it promises. + +This CIP aims to provide this explanation to enable everyone to understand the financial transactions and reports of organisations and thus bringing real transparency and enhancing trust of organisations willing to share their financial data on-chain. +To achieve this, the format must be as easy as possible to read and understand for humans, while still being machine-readable to allow for automated processing. + +**This readability comes with a price:** the format is not as compact as it could be, but this is a trade-off that is worth making to achieve the goal of transparency. + +# Specification + +This proposal defines how to structure metadata to anchor financial transactions and reports on-chain, ensuring they are both human-readable and machine-interpretable. +These metadata can be attached to any transaction. +The target of this metadata is to ensure flexibility for organisations. Reports differ between organisations, since they have different purposes, structures, and reporting periods. +The metadata structure is designed to be extensible, allowing for future enhancements without breaking existing implementations. + +## General structure + +The general structure contains the base information of the organisation, the metadata version, and the type of these financial records. +The json structure is as follows: +``` +"1447": { + "org": { + "id": "string", // Unique identifier for the organisation + "name": "string", // Name of the organisation + ... // Additional organisation-specific metadata can be added here + }, + "metadata": { + "version": "1.1" // Version of the metadata format + }, + "type": "string", // Type of the metadata + "data": // data object is defined through the Type of the metadata +} +``` + +The type can have two values: +- `INDIVIDUAL_TRANSACTIONS`: This type is used to anchor individual financial transactions of the organisation. +- `REPORT`: This type is used to anchor a custom report of the organisation + +### Individual Transactions +Additionally to the general structure the type `INDIVIDUAL_TRANSACTIONS` stores the individual transactions of the organisation within the data object. + +Required fields: + +| Field | Type | Description | +|----------|--------|----------------------------------------------------------------------------------------------------------------| +| `number` | string | Unique identifier for the transaction given from the accounting system used for identifying the transaction | +| `type` | string | Type of the transaction (e.g., "income", "expense", "transfer") | +| `date` | string | Date of the transaction in ISO 8601 format (YYYY-MM-DD) | +| `items` | array | Array of items in the transaction, each item can have additional fields like event, project, cost center, etc. | + +Additional fields can be added to the data object, such as accounting period, custom id, etc. + +Items are the individual financial entries within the transaction. Each item can have the following fields: + +| Field | Type | Description | +|----------------|--------|-------------------------------------------------------------------------------------------------------------------| +| `id` | string | Unique identifier for the item, e.g., a unique identifier from the accounting system | +| `amount` | string | Amount of the transaction item, represented as a string to allow for large numbers and decimal precision | +| `fx_rate` | string | Foreign exchange rate if applicable, represented as a string to allow for decimal precision | +| `document` | object | Document details related to the transaction item, can include number, currency, event, project, cost center, etc. | +| `event` | object | Optional event details related to the transaction item, can include code and name | +| `project` | object | Optional project details related to the transaction item, can include cust_code and name | +| `cost_center` | object | Optional cost center details related to the transaction item, can include cust_code and name | +| `vat` | object | Optional VAT details related to the transaction item, can include cust_code and rate | +| `counterparty` | object | Optional counterparty details related to the transaction item, can include cust_code and type | + +Example json +```json +{ + , + "type": "INDIVIDUAL_TRANSACTIONS", + "data": [ + { + "number": "Transaction123", + "type": "JOURNAL", + "date": "2025-01-01", + "accounting_period": "2025-12", + "items": [ + { + "id": "UniqueIdentifier123", + "amount": "2874", + "fx_rate": "0.93", + "document": { + "number": "JE-5810", + "currency": { + "id": "ISO_4217:EUR", + "cust_code": "EUR" + } + }, + "cost_center": { + "cust_code": "1000", + "name": "Internal Operations" + } + } + ] + } + ] +} +``` + +### Report +The type `REPORT` is used to publish reports of organisation. These reports can be highly customized resulting in the need for a flexible and adjustable structure. + +Required fields: + +| Field | Type | Description | +|-------------|-----------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `interval` | string | The reporting interval, e.g., "YEARLY", "QUARTERLY", "MONTHLY", etc. | +| `year` | string | The year of the report, e.g., "2025". | +| `period` | integer | The period of the report according to the interval, e.g., if Monthly 1 for January, 2 for February, etc. | +| `subtype` | string | Definition of what of the report type - Organisations can have custom reports, e.g., "BALANCE_SHEET", "INCOME_STATEMENT" | +| `data` | anyOf [string, data object] | The actual report data, which can be highly customized and structured according to the organisation's needs. This object should repesent categories and subcategories. | + +#### Example json: + +```json +{ + , + "type": "REPORT", + "interval": "MONTHLY", + "year": "2025", + "period": 12, + "subtype": "BALANCE_SHEET", + "data": { + "assets": { + "current_assets": { + "cash": "1000" + }, + "non_current_assets": { + "property": "5000" + } + }, + "liabilities": { + "current_liabilities": { + "accounts_payable": "200" + }, + "non_current_liabilities": { + "long_term_debt": "1000" + } + } + } +} +``` + +# Glossary +Since some terms within this CIP require specific definitions to ensure clarity and consistency, the following glossary is provided: +- **Cost Center**: A department or function within an organization that incurs costs but does not directly generate profit (e.g., the IT or Human Resources department). It is used for internal cost tracking. +- **Counterparty**: The other party that participates in a financial transaction. For example, in a sales transaction, the customer is the counterparty to the seller. +- **Foreign Exchange (FX) Rate**: The rate at which one currency can be exchanged for another. It is used when a transaction involves multiple currencies. +- **Value-Added Tax (VAT)**: A consumption tax placed on a product whenever value is added at each stage of the supply chain, from production to the point of sale. +- **Document**: A formal record of a transaction, which can include invoices, receipts, or other financial documents that provide evidence of the transaction. \ No newline at end of file From f08d67a513d02c571b0b72b6cbed0ac6e96ad829 Mon Sep 17 00:00:00 2001 From: Kammerlo Date: Thu, 17 Jul 2025 10:55:56 +0200 Subject: [PATCH 05/31] docs: added json schema + cddl description --- CIP-1447/README.md | 9 +- CIP-1447/version_1.1_onchain.cddl | 94 +++++++++ CIP-1447/version_1.1_onchain.json | 305 ++++++++++++++++++++++++++++++ 3 files changed, 405 insertions(+), 3 deletions(-) create mode 100644 CIP-1447/version_1.1_onchain.cddl create mode 100644 CIP-1447/version_1.1_onchain.json diff --git a/CIP-1447/README.md b/CIP-1447/README.md index bd792caf51..ef3f3e2a0d 100644 --- a/CIP-1447/README.md +++ b/CIP-1447/README.md @@ -5,6 +5,7 @@ Category: Metadata Status: Proposed Authors: - Thomas Kammerlocher + - Mateusz Czeladka Implementors: - Reeve: https://github.com/cardano-foundation/cf-reeve-platform Discussions: @@ -42,12 +43,14 @@ The metadata structure is designed to be extensible, allowing for future enhance The general structure contains the base information of the organisation, the metadata version, and the type of these financial records. The json structure is as follows: -``` +```json "1447": { "org": { - "id": "string", // Unique identifier for the organisation + "id": "string", // SHA3-256 hash of :: "name": "string", // Name of the organisation - ... // Additional organisation-specific metadata can be added here + "currency_id": "ISO_4217:XXX", // ISO 4217 currency code of the organisation + "country_code": "CH" // ISO 3166-1 alpha-2 country code of the organisation + "tax_id_number": "string" // tax identification number of the organisation }, "metadata": { "version": "1.1" // Version of the metadata format diff --git a/CIP-1447/version_1.1_onchain.cddl b/CIP-1447/version_1.1_onchain.cddl new file mode 100644 index 0000000000..f8270e0af5 --- /dev/null +++ b/CIP-1447/version_1.1_onchain.cddl @@ -0,0 +1,94 @@ +; Main entry point for the financial data structure +; The top-level key is a transaction metadata label, represented as an integer. +financial_data = { + * uint => cipBody +} + +; The main body of the CIP data, which can be one of two types. +cipBody = { + org: organisation, + metadata: metadataInfo, + ( report / individualTransactions ) +} + +; -- Organisation and Metadata Definitions -- + +organisation = { + id: tstr .regexp "^[a-fA-F0-9]{64}$", ; SHA3-256 hash + name: tstr, + currency_id: tstr .regexp "^ISO_4217:[A-Z]{3}$", + country_code: tstr .regexp "^[A-Z]{2}$", + tax_id_number: tstr, +} + +metadataInfo = { + version: tstr, +} + +; -- Report Type Definition -- + +report = { + type: "REPORT", + interval: tstr, + year: tstr .regexp "^[12][0-9]{3}$", + period: uint, + subtype: tstr, + data: (tstr / recursiveObject), + * tstr => any ; Allows for additional, non-specified properties +} + +; -- Individual Transactions Type Definition -- + +individualTransactions = { + type: "INDIVIDUAL_TRANSACTIONS", + data: [+ transaction] ; Array of one or more transactions +} + +transaction = { + number: tstr, + type: tstr, + date: tstr, ; Should conform to ISO 8601 date format, e.g., "YYYY-MM-DD" + items: [+ lineItem], + * tstr => any ; Allows for additional properties like 'accounting_period' +} + +lineItem = { + id: tstr, + amount: tstr, + fx_rate: tstr, + document: document, + ? event: eventDetail, + ? project: classificationDetail, + ? cost_center: classificationDetail, + ? vat: classificationDetail, + ? counterparty: classificationDetail, + * tstr => any ; Allows for additional, non-specified properties +} + +; -- Reusable Component Definitions -- + +document = { + number: tstr, + currency: currency, +} + +currency = { + cust_code: tstr, + id: tstr .regexp "^ISO_4217:[A-Z]{3}$", +} + +eventDetail = { + code: tstr, + name: tstr, +} + +; A reusable structure for dimensional data like project, cost center, etc. +classificationDetail = { + cust_code: tstr, + name: tstr, +} + +; A recursive structure for nested report data (e.g., categories/subcategories) +recursiveObject = { + * tstr => (tstr / recursiveObject) +} diff --git a/CIP-1447/version_1.1_onchain.json b/CIP-1447/version_1.1_onchain.json new file mode 100644 index 0000000000..ccc7aa72f6 --- /dev/null +++ b/CIP-1447/version_1.1_onchain.json @@ -0,0 +1,305 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "CIP Financial Data Standard", + "description": "A schema for anchoring financial transactions and reports on-chain, based on the specified CIP format.", + "type": "object", + "patternProperties": { + "^[0-9]+$": { + "$ref": "#/definitions/cipBody" + } + }, + "additionalProperties": false, + "definitions": { + "cipBody": { + "type": "object", + "properties": { + "org": { + "$ref": "#/definitions/organisation" + }, + "metadata": { + "$ref": "#/definitions/metadataInfo" + } + }, + "oneOf": [ + { + "$ref": "#/definitions/report" + }, + { + "$ref": "#/definitions/individualTransactions" + } + ], + "required": [ + "org", + "metadata" + ], + "additionalProperties": false + }, + "organisation": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "SHA3-256 hash of ::.", + "pattern": "^[a-fA-F0-9]{64}$" + }, + "name": { + "type": "string", + "description": "Name of the organisation." + }, + "currency_id": { + "type": "string", + "description": "Default currency of the organisation, formatted as ISO_4217:.", + "pattern": "^ISO_4217:[A-Z]{3}$" + }, + "country_code": { + "type": "string", + "description": "ISO 3166-1 alpha-2 country code of the organisation.", + "pattern": "^[A-Z]{2}$" + }, + "tax_id_number": { + "type": "string", + "description": "Tax identification number of the organisation." + } + }, + "required": [ + "id", + "name", + "currency_id", + "country_code", + "tax_id_number" + ], + "additionalProperties": true + }, + "metadataInfo": { + "type": "object", + "properties": { + "version": { + "type": "string", + "description": "Version of the metadata format." + } + }, + "required": [ + "version" + ] + }, + "report": { + "type": "object", + "properties": { + "type": { + "const": "REPORT" + }, + "interval": { + "type": "string", + "description": "The reporting interval, e.g., 'YEARLY', 'QUARTERLY', 'MONTHLY'." + }, + "year": { + "type": "string", + "description": "The four-digit year of the report.", + "pattern": "^[12][0-9]{3}$" + }, + "period": { + "type": "integer", + "description": "The period of the report according to the interval.", + "minimum": 1 + }, + "subtype": { + "type": "string", + "description": "The specific type of report, e.g., 'BALANCE_SHEET'." + }, + "data": { + "description": "Custom report data, which can be a simple string or a nested object representing categories and subcategories.", + "anyOf": [ + { + "type": "string" + }, + { + "$ref": "#/definitions/recursiveObject" + } + ] + } + }, + "required": [ + "type", + "interval", + "year", + "period", + "subtype", + "data" + ], + "additionalProperties": true + }, + "individualTransactions": { + "type": "object", + "properties": { + "type": { + "const": "INDIVIDUAL_TRANSACTIONS" + }, + "data": { + "type": "array", + "items": { + "$ref": "#/definitions/transaction" + } + } + }, + "required": [ + "type", + "data" + ], + "additionalProperties": false + }, + "transaction": { + "type": "object", + "properties": { + "number": { + "type": "string" + }, + "type": { + "type": "string" + }, + "date": { + "type": "string", + "format": "date" + }, + "items": { + "type": "array", + "items": { + "$ref": "#/definitions/lineItem" + }, + "minItems": 1 + } + }, + "required": [ + "number", + "type", + "date", + "items" + ], + "additionalProperties": true + }, + "lineItem": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "amount": { + "type": "string" + }, + "fx_rate": { + "type": "string" + }, + "document": { + "$ref": "#/definitions/document" + }, + "event": { + "$ref": "#/definitions/eventDetail" + }, + "project": { + "$ref": "#/definitions/classificationDetail" + }, + "cost_center": { + "$ref": "#/definitions/classificationDetail" + }, + "vat": { + "$ref": "#/definitions/classificationDetail" + }, + "counterparty": { + "$ref": "#/definitions/classificationDetail" + } + }, + "required": [ + "id", + "amount", + "fx_rate", + "document" + ], + "additionalProperties": true + }, + "eventDetail": { + "type": "object", + "description": "Details about the event associated with the transaction, such as code and name.", + "properties": { + "code": { + "type": "string", + "description": "Event code, e.g., '71103100'." + }, + "name": { + "type": "string", + "description": "Name of the event, e.g., 'Payroll Expenses - Salaries and wages/Accounts payable'." + } + }, + "required": [ + "code", + "name" + ] + }, + "classificationDetail": { + "type": "object", + "description": "Details for classification such as project, cost center, VAT, or counterparty.", + "properties": { + "cust_code": { + "type": "string", + "description": "Custom code for the classification, e.g., '9000' for cost center." + }, + "name": { + "type": "string", + "description": "Name of the classification, e.g., 'Internal' for cost center." + } + }, + "required": [ + "cust_code", + "name" + ] + }, + "document": { + "type": "object", + "description": "A formal record of a transaction, which can include invoices, receipts", + "properties": { + "number": { + "type": "string", + "description": "Document number or identifier." + }, + "currency": { + "$ref": "#/definitions/currency" + } + }, + "required": [ + "number", + "currency" + ] + }, + "currency": { + "type": "object", + "description": "Currency information, formatted as ISO_4217:.", + "properties": { + "cust_code": { + "type": "string", + "description": "Custom code for the currency, e.g., 'USD'." + }, + "id": { + "type": "string", + "description": "Currency identifier, formatted as ISO_4217:.", + "pattern": "^ISO_4217:[A-Z]{3}$" + } + }, + "required": [ + "cust_code", + "id" + ] + }, + "recursiveObject": { + "type": "object", + "description": "A flexible object for categories and subcategories where each value can be a string or another nested object.", + "additionalProperties": { + "anyOf": [ + { + "type": "string" + }, + { + "$ref": "#/definitions/recursiveObject" + } + ] + } + } + } +} \ No newline at end of file From c0bcf5af1d6cacaaad28d9143d271771c657f7e8 Mon Sep 17 00:00:00 2001 From: Kammerlo Date: Thu, 17 Jul 2025 11:19:35 +0200 Subject: [PATCH 06/31] docs: added id to transactions as required field --- CIP-1447/README.md | 14 ++++++++------ CIP-1447/version_1.1_onchain.cddl | 1 + CIP-1447/version_1.1_onchain.json | 6 ++++++ 3 files changed, 15 insertions(+), 6 deletions(-) diff --git a/CIP-1447/README.md b/CIP-1447/README.md index ef3f3e2a0d..a659ff11ee 100644 --- a/CIP-1447/README.md +++ b/CIP-1447/README.md @@ -69,12 +69,13 @@ Additionally to the general structure the type `INDIVIDUAL_TRANSACTIONS` stores Required fields: -| Field | Type | Description | -|----------|--------|----------------------------------------------------------------------------------------------------------------| -| `number` | string | Unique identifier for the transaction given from the accounting system used for identifying the transaction | -| `type` | string | Type of the transaction (e.g., "income", "expense", "transfer") | -| `date` | string | Date of the transaction in ISO 8601 format (YYYY-MM-DD) | -| `items` | array | Array of items in the transaction, each item can have additional fields like event, project, cost center, etc. | +| Field | Type | Description | +|----------|--------|------------------------------------------------------------------------------------------------------------------------------------| +| `id` | string | Unique identifier for the organisation, SHA3-256 hash of organisation ID and the transactionn number (e.g., "::") | +| `number` | string | Unique identifier for the transaction given from the accounting system used for identifying the transaction | +| `type` | string | Type of the transaction (e.g., "income", "expense", "transfer") | +| `date` | string | Date of the transaction in ISO 8601 format (YYYY-MM-DD) | +| `items` | array | Array of items in the transaction, each item can have additional fields like event, project, cost center, etc. | Additional fields can be added to the data object, such as accounting period, custom id, etc. @@ -99,6 +100,7 @@ Example json "type": "INDIVIDUAL_TRANSACTIONS", "data": [ { + "id": "string", // SHA3-256 hash of :: "number": "Transaction123", "type": "JOURNAL", "date": "2025-01-01", diff --git a/CIP-1447/version_1.1_onchain.cddl b/CIP-1447/version_1.1_onchain.cddl index f8270e0af5..d3b9320acb 100644 --- a/CIP-1447/version_1.1_onchain.cddl +++ b/CIP-1447/version_1.1_onchain.cddl @@ -45,6 +45,7 @@ individualTransactions = { } transaction = { + id: tstr .regexp "^[a-fA-F0-9]{64}$", ; SHA3-256 hash number: tstr, type: tstr, date: tstr, ; Should conform to ISO 8601 date format, e.g., "YYYY-MM-DD" diff --git a/CIP-1447/version_1.1_onchain.json b/CIP-1447/version_1.1_onchain.json index ccc7aa72f6..47f8f2dd1b 100644 --- a/CIP-1447/version_1.1_onchain.json +++ b/CIP-1447/version_1.1_onchain.json @@ -150,6 +150,11 @@ "transaction": { "type": "object", "properties": { + "id": { + "type": "string", + "description": "SHA3-256 hash of ::.", + "pattern": "^[a-fA-F0-9]{64}$" + }, "number": { "type": "string" }, @@ -169,6 +174,7 @@ } }, "required": [ + "id", "number", "type", "date", From 1fbe657754cd6816a4be78fe6265a14acead62fa Mon Sep 17 00:00:00 2001 From: Kammerlo Date: Fri, 18 Jul 2025 07:42:27 +0200 Subject: [PATCH 07/31] docs: added more explanation about the tradeoff in motivation --- CIP-1447/README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CIP-1447/README.md b/CIP-1447/README.md index a659ff11ee..ab53c57cbb 100644 --- a/CIP-1447/README.md +++ b/CIP-1447/README.md @@ -32,6 +32,10 @@ To achieve this, the format must be as easy as possible to read and understand f **This readability comes with a price:** the format is not as compact as it could be, but this is a trade-off that is worth making to achieve the goal of transparency. +However, this is a necessary investment in universal accessibility and long-term trust. +It ensures that any person, from an accountant to a stakeholder, can view the raw data on a block explorer and understand it immediately, without needing specialized software. +This approach guarantees that the financial records remain transparent and independently verifiable, ensuring their value and integrity persist even if the application used to publish them shuts down. + # Specification This proposal defines how to structure metadata to anchor financial transactions and reports on-chain, ensuring they are both human-readable and machine-interpretable. From 7b1d9d6e2628167585e70d96100ed4deb2d48911 Mon Sep 17 00:00:00 2001 From: Kammerlo Date: Fri, 18 Jul 2025 14:03:27 +0200 Subject: [PATCH 08/31] docs: incorporating feedback --- CIP-1447/README.md | 65 +++++++++++++++++++++++++++++----------------- 1 file changed, 41 insertions(+), 24 deletions(-) diff --git a/CIP-1447/README.md b/CIP-1447/README.md index ab53c57cbb..f82740c4cb 100644 --- a/CIP-1447/README.md +++ b/CIP-1447/README.md @@ -52,12 +52,12 @@ The json structure is as follows: "org": { "id": "string", // SHA3-256 hash of :: "name": "string", // Name of the organisation - "currency_id": "ISO_4217:XXX", // ISO 4217 currency code of the organisation - "country_code": "CH" // ISO 3166-1 alpha-2 country code of the organisation + "currency_id": "string", // ISO 4217 currency code of the organisation + "country_code": "string" // ISO 3166-1 alpha-2 country code of the organisation "tax_id_number": "string" // tax identification number of the organisation }, "metadata": { - "version": "1.1" // Version of the metadata format + "version": "1.string" // Version of the metadata format }, "type": "string", // Type of the metadata "data": // data object is defined through the Type of the metadata @@ -69,33 +69,50 @@ The type can have two values: - `REPORT`: This type is used to anchor a custom report of the organisation ### Individual Transactions -Additionally to the general structure the type `INDIVIDUAL_TRANSACTIONS` stores the individual transactions of the organisation within the data object. +Additionally to the general structure the type `INDIVIDUAL_TRANSACTIONS` stores the individual accounting transactions of the organisation within the data object. Required fields: -| Field | Type | Description | -|----------|--------|------------------------------------------------------------------------------------------------------------------------------------| -| `id` | string | Unique identifier for the organisation, SHA3-256 hash of organisation ID and the transactionn number (e.g., "::") | -| `number` | string | Unique identifier for the transaction given from the accounting system used for identifying the transaction | -| `type` | string | Type of the transaction (e.g., "income", "expense", "transfer") | -| `date` | string | Date of the transaction in ISO 8601 format (YYYY-MM-DD) | -| `items` | array | Array of items in the transaction, each item can have additional fields like event, project, cost center, etc. | +| Field | Type | Description | +|----------|--------|----------------------------------------------------------------------------------------------------------------------------------------| +| `id` | string | Unique identifier for the organisation, SHA3-256 hash of organisation ID and the transactionn number (e.g., "::") | +| `number` | string | Unique identifier for the transaction given from the accounting system used for identifying the transaction | +| `type` | enum | Type of the transaction represented as an enum to limit the space. The list of specific transactions types can be extended. | +| `date` | string | Date of the transaction in ISO 8601 format (YYYY-MM-DD) | +| `items` | array | Array of items in the transaction, each item represents an event and can have additional fields like event, project, cost center, etc. | + +The list of possible transactions type is to be extended, but the following types are defined as a starting point: + +| Type | Description | +|-------------------|----------------------------------------------------------------------------------------------| +| `Journal` | General journal entry, used for recording various financial transactions | +| `VendorBill` | Bill from a vendor, representing an amount owed to a supplier | +| `VendorPayment` | Payment made to a vendor, reducing the amount owed to them | +| `CustomerInvoice` | Invoice issued to a customer, representing an amount owed by them | +| `CustomerPayment` | Payment received from a customer, reducing the amount owed by them | +| `BILL_CREDIT` | Credit note issued against a vendor bill, reducing the amount owed to the vendor | +| `CARD_CHARGE` | Charge made to a credit card, representing an expense incurred by the organisation | +| `CARD_REFUND` | Refund issued to a credit card, representing a return of funds to the organisation's card | +| `FX_REVALUATION` | Foreign exchange revaluation, used to adjust the value of foreign currency transactions | +| `TRANSFER` | Transfer of funds between accounts, representing a movement of money within the organisation | +| `EXPENSE_REPORT` | Report of expenses incurred by employees, summarizing various costs and reimbursements | Additional fields can be added to the data object, such as accounting period, custom id, etc. +#### Transaction Items Items are the individual financial entries within the transaction. Each item can have the following fields: -| Field | Type | Description | -|----------------|--------|-------------------------------------------------------------------------------------------------------------------| -| `id` | string | Unique identifier for the item, e.g., a unique identifier from the accounting system | -| `amount` | string | Amount of the transaction item, represented as a string to allow for large numbers and decimal precision | -| `fx_rate` | string | Foreign exchange rate if applicable, represented as a string to allow for decimal precision | -| `document` | object | Document details related to the transaction item, can include number, currency, event, project, cost center, etc. | -| `event` | object | Optional event details related to the transaction item, can include code and name | -| `project` | object | Optional project details related to the transaction item, can include cust_code and name | -| `cost_center` | object | Optional cost center details related to the transaction item, can include cust_code and name | -| `vat` | object | Optional VAT details related to the transaction item, can include cust_code and rate | -| `counterparty` | object | Optional counterparty details related to the transaction item, can include cust_code and type | +| Field | Type | Description | +|----------------|--------|----------------------------------------------------------------------------------------------------------------------| +| `id` | string | Unique identifier for the item, SHA3-256 hash of the transaction id and the item number | +| `amount` | string | Monetary amount of the transaction item, in the item currency | +| `fx_rate` | string | Foreign exchange rate on effect at the date of the transaction, that converts the amount to the functional currency. | +| `document` | object | Document details related to the transaction item, can include number, currency, event, project, cost center, etc. | +| `event` | object | Event details related to the transaction item, can include code and name | +| `project` | object | Optional project details related to the transaction item, can include cust_code and name | +| `cost_center` | object | Optional cost center details related to the transaction item, can include cust_code and name | +| `vat` | object | Optional VAT details related to the transaction item, can include cust_code and rate | +| `counterparty` | object | Optional counterparty details related to the transaction item, can include cust_code and type | Example json ```json @@ -111,7 +128,7 @@ Example json "accounting_period": "2025-12", "items": [ { - "id": "UniqueIdentifier123", + "id": "string", // SHA3-256 hash of :: "amount": "2874", "fx_rate": "0.93", "document": { @@ -141,7 +158,7 @@ Required fields: |-------------|-----------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `interval` | string | The reporting interval, e.g., "YEARLY", "QUARTERLY", "MONTHLY", etc. | | `year` | string | The year of the report, e.g., "2025". | -| `period` | integer | The period of the report according to the interval, e.g., if Monthly 1 for January, 2 for February, etc. | +| `period` | integer | The period of the report according to the interval, e.g., if Monthly 1 for January, 2 for February, if quarterly 1 for Q1, 2 for Q2 | | `subtype` | string | Definition of what of the report type - Organisations can have custom reports, e.g., "BALANCE_SHEET", "INCOME_STATEMENT" | | `data` | anyOf [string, data object] | The actual report data, which can be highly customized and structured according to the organisation's needs. This object should repesent categories and subcategories. | From 808cb6bdcdc04af19b628dc5ab1f9dac6c90403d Mon Sep 17 00:00:00 2001 From: Kammerlo Date: Fri, 18 Jul 2025 14:03:41 +0200 Subject: [PATCH 09/31] docs: incorporating feedback --- CIP-1447/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CIP-1447/README.md b/CIP-1447/README.md index f82740c4cb..84f7640f78 100644 --- a/CIP-1447/README.md +++ b/CIP-1447/README.md @@ -57,7 +57,7 @@ The json structure is as follows: "tax_id_number": "string" // tax identification number of the organisation }, "metadata": { - "version": "1.string" // Version of the metadata format + "version": "string" // Version of the metadata format }, "type": "string", // Type of the metadata "data": // data object is defined through the Type of the metadata From 506132b0b73209c10ad4ad8df5ff0ebbc9f76f59 Mon Sep 17 00:00:00 2001 From: Kammerlo Date: Tue, 22 Jul 2025 10:05:08 +0200 Subject: [PATCH 10/31] docs: added CPS for linking offChain identites --- CPS-????/README.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 CPS-????/README.md diff --git a/CPS-????/README.md b/CPS-????/README.md new file mode 100644 index 0000000000..fba6fcce88 --- /dev/null +++ b/CPS-????/README.md @@ -0,0 +1,50 @@ +--- +CPS: ???? +Title: Linking Off-Chain identity solutions to On-Chain Transactions +Status: Open +Category: Identity +Authors: + - +Proposed Solutions: + - +Discussions: + - +Created: 2025-07-09 +License: _ +--- + +## Abstract + +Transactions often involve multiple parties, including individuals and organisations. +To facilitate these interactions, it is essential to have a reliable way to verify the identities of participants. +Most of the organisations have off-chain identities, which they could leverage to enhance the trust and security of their on-chain transactions. +Off-chain identities could be solutions like: [GLEIF](https://www.gleif.org/en), [KERI Identifiers](https://identity.foundation/keri/), ... +While Cardano's on-chain data model provides a robust framework for transaction verification, it lacks a standardized mechanism for off-chain identity verification. + +This limitation makes it difficult to verify the identity of participants, establish trust, and comply with regulatory requirements. +This problem statement outlines the need for a standardized solution for off-chain identity verification on Cardano to enhance trust, security, and adoption. + +## Problem + +The core problem is the absence of a standardized, self-sustaining and user-friendly solution for linking decentralized off-chain identifiers to on-chain transaction on the Cardano blockchain. +This gap creates several challenges: +- **Trust and Security**: Without a reliable way to verify identities, it is difficult to establish trust between parties involved in transactions. This can lead to fraud, manipulation, and other security issues. +- **Compliance**: Many industries require strict compliance with regulations related to identity verification. The lack of a standardized solution makes it challenging for businesses and organizations to meet these requirements. +- **User Experience**: Current solutions for off-chain identity verification are often fragmented and complex, leading to a poor user experience. Making it impossible for others to integrate these solutions e.g. explorers + +## Use cases +The need for a standardized solution for decentralized off-chain identity verification on Cardano is driven by several use cases, including: +- **Accountability**: When publishing financial reports, it is essential to verify the identity of the individuals or organizations responsible for the report. This helps to ensure that the information is accurate and trustworthy. +- **Supply Chain Tracking**: In supply chain, parties involved in the process need to verify the identity of each other to ensure that the products are genuine and meet quality standards. + This is particularly important in industries such as pharmaceuticals, where counterfeit products can have serious consequences. + +## Goals + +The goal of this problem statement is to initiate a discussion within the Cardano community about the need for a standardized framework for off-chain identity verification. +The ultimate objective is to develop a solution that: +- **Is secure and trustworthy**: The solution should provide a high degree of security and be resistant to fraud and manipulation. +- **Is self-sustaining**: The solution should be able to operate independently of any single entity or organization, ensuring decentralization and resilience. +- **Is interoperable**: The solution should be compatible with a wide range of applications and services. (For example easy to integrate into existing solutions, like explorers, wallets, and dApps.) +- **Is compliant with regulations**: The solution should help businesses and organizations to comply with relevant regulations. + +The solution should be able to handle different types of identify solutions, so it shouldn't be tied to a specific identity solution, but rather provide a framework for integrating different solutions. \ No newline at end of file From 1952ecde8f16785459d1c6568506dd8a689231f3 Mon Sep 17 00:00:00 2001 From: Robert Phair Date: Wed, 23 Jul 2025 00:00:55 -0400 Subject: [PATCH 11/31] applying `Tools` category Co-authored-by: Ryan --- CPS-????/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CPS-????/README.md b/CPS-????/README.md index fba6fcce88..6cadc5ea90 100644 --- a/CPS-????/README.md +++ b/CPS-????/README.md @@ -2,7 +2,7 @@ CPS: ???? Title: Linking Off-Chain identity solutions to On-Chain Transactions Status: Open -Category: Identity +Category: Tools Authors: - Proposed Solutions: From 0ccfacffef1c1866b1cdd1ec70a80f2858365c71 Mon Sep 17 00:00:00 2001 From: Robert Phair Date: Wed, 23 Jul 2025 00:01:50 -0400 Subject: [PATCH 12/31] applying seminal discussion link to header Co-authored-by: Ryan --- CPS-????/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CPS-????/README.md b/CPS-????/README.md index 6cadc5ea90..8cae8ea8f3 100644 --- a/CPS-????/README.md +++ b/CPS-????/README.md @@ -8,7 +8,7 @@ Authors: Proposed Solutions: - Discussions: - - + - https://github.com/cardano-foundation/CIPs/pull/1059 Created: 2025-07-09 License: _ --- From 1af1f1e41315260c3abf332e14ec374a8d89fb5f Mon Sep 17 00:00:00 2001 From: Kammerlo Date: Wed, 23 Jul 2025 07:51:48 +0200 Subject: [PATCH 13/31] docs: update template, incorporated feedback --- CPS-????/README.md | 24 ++++++++++++++++++------ 1 file changed, 18 insertions(+), 6 deletions(-) diff --git a/CPS-????/README.md b/CPS-????/README.md index 8cae8ea8f3..39a13b50c7 100644 --- a/CPS-????/README.md +++ b/CPS-????/README.md @@ -1,16 +1,17 @@ --- CPS: ???? -Title: Linking Off-Chain identity solutions to On-Chain Transactions +Title: Linking Off-Chain identities Status: Open Category: Tools Authors: - - -Proposed Solutions: - - + - Thomas Kammerlocher + - Fergal O'Connor + - Roberto C. Morano +Proposed Solutions: [] Discussions: - https://github.com/cardano-foundation/CIPs/pull/1059 Created: 2025-07-09 -License: _ +License: Apache-2.0 --- ## Abstract @@ -37,6 +38,8 @@ The need for a standardized solution for decentralized off-chain identity verifi - **Accountability**: When publishing financial reports, it is essential to verify the identity of the individuals or organizations responsible for the report. This helps to ensure that the information is accurate and trustworthy. - **Supply Chain Tracking**: In supply chain, parties involved in the process need to verify the identity of each other to ensure that the products are genuine and meet quality standards. This is particularly important in industries such as pharmaceuticals, where counterfeit products can have serious consequences. +- **Verifying governance actors**: In decentralized governance systems, it is crucial to verify the identity of participants to ensure that decisions are made by legitimate actors. + This helps to prevent manipulation and ensures that the governance process is transparent and accountable. ## Goals @@ -47,4 +50,13 @@ The ultimate objective is to develop a solution that: - **Is interoperable**: The solution should be compatible with a wide range of applications and services. (For example easy to integrate into existing solutions, like explorers, wallets, and dApps.) - **Is compliant with regulations**: The solution should help businesses and organizations to comply with relevant regulations. -The solution should be able to handle different types of identify solutions, so it shouldn't be tied to a specific identity solution, but rather provide a framework for integrating different solutions. \ No newline at end of file +The solution should be able to handle different types of identify solutions, so it shouldn't be tied to a specific identity solution, but rather provide a framework for integrating different solutions. + +## Open Questions +1. How to verify the identity of participants in a decentralized manner? +2. How manage the lifecycle of off-chain identities, including creation, update, and revocation? +3. What is the right on-chain anchor for identity: metadata, an NFT, or something else? + +## Copyright + +This CIP is licensed under [Apache-2.0](http://www.apache.org/licenses/LICENSE-2.0). \ No newline at end of file From 8c81002f94c45faea97cf67a34afc8ae1a485cb3 Mon Sep 17 00:00:00 2001 From: Robert Phair Date: Wed, 23 Jul 2025 10:51:02 -0400 Subject: [PATCH 14/31] correcting title capitalisation after https://github.com/cardano-foundation/CIPs/pull/1059/commits/1af1f1e41315260c3abf332e14ec374a8d89fb5f --- CPS-????/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CPS-????/README.md b/CPS-????/README.md index 39a13b50c7..01a15257e6 100644 --- a/CPS-????/README.md +++ b/CPS-????/README.md @@ -1,6 +1,6 @@ --- CPS: ???? -Title: Linking Off-Chain identities +Title: Linking Off-Chain Identities Status: Open Category: Tools Authors: @@ -59,4 +59,4 @@ The solution should be able to handle different types of identify solutions, so ## Copyright -This CIP is licensed under [Apache-2.0](http://www.apache.org/licenses/LICENSE-2.0). \ No newline at end of file +This CIP is licensed under [Apache-2.0](http://www.apache.org/licenses/LICENSE-2.0). From bb30aa8289ed124465c158d6e954852e5578e907 Mon Sep 17 00:00:00 2001 From: Kammerlo Date: Wed, 5 Nov 2025 07:59:05 +0100 Subject: [PATCH 15/31] docs: first draft of the KERI CIP --- CIP-0010/registry.json | 4 + CIP-????/README.md | 225 ++++++++++++++++++++++++++++++++++++++++ CIP-????/version_1.cddl | 35 +++++++ CIP-????/version_1.json | 106 +++++++++++++++++++ 4 files changed, 370 insertions(+) create mode 100644 CIP-????/README.md create mode 100644 CIP-????/version_1.cddl create mode 100644 CIP-????/version_1.json diff --git a/CIP-0010/registry.json b/CIP-0010/registry.json index 3d421a6f06..675f0da41c 100644 --- a/CIP-0010/registry.json +++ b/CIP-0010/registry.json @@ -154,5 +154,9 @@ { "transaction_metadatum_label": 61286, "description": "CIP-0015 - Catalyst deregistration" + }, + { + "transaction_metadatum_label": "????", + "description": "CIP-???? - Keri Decentralized Identifiers" } ] diff --git a/CIP-????/README.md b/CIP-????/README.md new file mode 100644 index 0000000000..9922cd9f8b --- /dev/null +++ b/CIP-????/README.md @@ -0,0 +1,225 @@ +--- +CIP: ???? +Title: Keri Decentralized Identifiers +Category: Metadata +Status: Proposed +Authors: + - Fergal O'Connor + - Thomas Kammerlocher +Implementors: + - reeve.technology + - veridian.id +Discussions: + - +Created: 2025-11-05 +License: CC-BY-4.0 +--- + +## Abstract + +Accountability is essential for legal entities, organizations, and authorities operating in regulated environments. To establish accountability on the Cardano blockchain, it must be possible to prove the identity of entities responsible for on-chain actions in a verifiable and interoperable way. +This CIP defines a standardized mechanism to embed KERI (Key Event Receipt Infrastructure) identifiers within Cardano transaction metadata. KERI provides self-certifying, portable, and decentralized identifiers known as Autonomic Identifiers (AIDs) that can be anchored to various roots of trust—such as verifiable Legal Entity Identifiers (vLEIs), organizational registries, or domain-specific trust frameworks. +By including KERI identifiers in transaction metadata, Cardano enables a flexible, trust-agnostic approach to identity binding. This approach supports accountability, legal and regulatory compliance, and interoperability with existing and emerging global identity ecosystems, while remaining compatible with self-sovereign identity principles. + +## Motivation: why is this CIP necessary? + +The need for auditable and verifiable identifiers is rising, as accountability, traceability, and transparency are essential pillars in regulated environments. Without a standardized mechanism, it is difficult to reliably link on-chain activity to persistent and legally recognized identities. +KERI (Key Event Receipt Infrastructure) addresses this challenge by providing a decentralized, key-oriented identifier system for secure, portable, and self-certifying digital identities. Rather than relying on centralized registries, KERI establishes identifiers through cryptographic event logs, enabling secure key rotation, continuity of control, and tamper-evident audit trails. This ensures that an identifier can consistently represent the same entity over time, while also being interoperable with verifiable credentials and root of trusts such as vLEIs. +By embedding KERI identifiers into Cardano transaction metadata, we create a standardized, verifiable connection between on-chain actions and off-chain accountability frameworks. This allows transactions to be cryptographically tied to a specific identifier and, through credential chains also published on-chain, to a legally recognized entity. + + +## Specification + +Below we define a generic solution to enable metadata signing where a particular ecosystem or use-case may leverage a root of trust of its choosing – each most likely with its own credential chain format. +The credentials used in the KERI ecosystem are known as ACDCs, or [Authentic Chained Data Containers](https://www.rfc-editor.org/rfc/rfc8174). This CIP will not explain at depth how KERI and ACDCs work due to their technical complexity. The appendix will however include some expanded explanations to help provide clarity. +Beyond the specification and as a useful reference, we will outline how credential chains for the vLEI ecosystem can be leveraged to provide high assurance to [Reeve](https://reeve.technology). + +> [!NOTE] +> The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119](https://www.rfc-editor.org/rfc/rfc2119) [RFC8174](https://www.rfc-editor.org/rfc/rfc8174) when, and only when, they appear in all capitals, as shown here. + +### Key Event Log Discovery + +In order to verify the validity of credential chains and metadata transactions, Key Event Logs, or KELs, for all issuing and holding identifiers in the credential chain must be made available to a verifier. KELs may live off-chain for interoperability and scalability reasons, so this CIP does not make assumptions on which medium the KELs are published. + +A KERI watcher network SHOULD be used to discover up-to-date KELs for a given identifier for certain security reasons. Discovery of the watcher network relevant to a given ecosystem depends on the ecosystem itself. + +However, as KERI is a maturing technology, wide-spread deployment of watcher networks is not yet guaranteed. Until then, the interim solution is to publish an Out-of-Band-Introduction to this Github repository for discovery, and this may be used by a verifier to discover and query for KEL events and updates. + +In one way or another, chain indexers must query for Key Event Log updates to validate credential chains and metadata transactions during the process of verification. + +### Establishment of signing authority +Before attesting to any transactions, the relevant credential chain for the controller must be published on-chain with the following attributes – most of which are used to help simplify indexing: +- **t** — A transaction type of `AUTH_BEGIN` is used to establish a signer’s authority using a credential chain. +- **i** — The identifier of the signer in the CESR qb64 variant. This MUST match the issuee of the leaf credential in the chain. +- **s** — The schema identifier of the leaf credential in the chain in the CESR qb64 variant. This MUST match the schema of the leaf credential in the chain. Why include? +- **m** — An optional metadata block used to simplify indexing for a particular use-case. For example, the LEI of a legal entity could be contained here. +- **c** — The byte-stream of the credential chain in the CESR qb2 variant, for brevity. + +The credential chain should contain all credentials, relevant registry events and attachments. There are various types of ACDC registries, so for simplicity: the credential chain MUST validate with an ACDC 1.0 or 2.0 verifier, assuming that KEL events are already available. + +These attributes can be embedded in the metadata of a transaction using a fixed metadata label. Compact field labels are used for brevity. + +The metadata is structured as follows: +```JSON +{ + "????": + { + t: "AUTH_BEGIN", + s: , + i: , + c: , + m: + } +} +``` +If valid for a given ecosystem, this transaction establishes the signing authority for `i` from this transaction onwards in the chain. The issuance date of the leaf credential SHOULD be ignored. + +### Creation of verifiable records +To create a persistent signature over data with KERI, signers can anchor a digest of the data in their KEL, typically using an interaction event. Anchoring ensures that data remains verifiable even if the controller later rotates their keys. + + The relevant data recorded for each event includes: +- **t** — A transaction type of `ATTEST` is to create a verifiable record. +- **i** — The identifier of the signer in the CESR qb64 variant. +- **d** — The digest of the data being signed in the CESR qb64 variant. +- **s** — The sequence number of the KERI event, encoded as a hex string. +If the KEL of identifier `i` contains an event at sequence number `s` which has a seal value of `{ d: }`, it serves as cryptographically verifiable proof that the data was effectively signed by the controller. +A reference to this event in a metadata transaction is structured as follows: +```JSON +{ + "????": { + "i": , + “d”: , + "s": , + “t”: “ATTEST” + }, + “YYYY”: {} // Metadata i can sign +} +``` +Such transactions are only considered valid if the digest value is correct, and can be found anchored in the KEL of the controller at the given sequence number. + +### Removal of signing authority +Signing authority may be removed after a period of time by revoking the relevant credential and publishing this revocation on-chain. As such, the validity of transactions associated with that credential chain are for all valid `ATTEST` transactions between issuance (`AUTH_BEGIN`) and revocation (`AUTH_END`). + +The following attributes are used: +- **t** — A transaction type of `AUTH_END` is used to remove a signer’s authority with revocation registry events. +- **i** — The identifier of the signer in the CESR qb64 variant. This MUST match the issuee of the leaf credential in the chain. +- **s** — The schema identifier of the leaf credential in the chain in the CESR qb64 variant. This MUST match the schema of the leaf credential in the chain. +- **m** — A metadata block used to simplify indexing for a particular use-case. For example, the LEI of a legal entity could be contained here. +- **c** — The byte-stream of the revocation registry events in the CESR qb2 variant, for brevity. +A reference to this event in a metadata transaction is structured as follows: +```JSON +{ + "????": + { + t: "AUTH_END", + s: , + i: , + c: , + m: + } +} + +``` +If the successful parsing of the revocation events results in a credential chain that no longer gives authority to the signer, any later ATTEST transactions for this credential chain should be ignored (unless there is another subsequent `AUTH_START`). + + +#### Reference Example - vLEI + +The Global Legal Entity Identifier Foundation (GLEIF) serves as the root of trust for Legal Entity Identifiers (LEIs) worldwide. Their verifiable variant, the vLEI, is based on the KERI and ACDC standards, and are issued by Qualified vLEI Issuers (QVIs). + +Legal entities holding valid vLEI credentials may issue other credentials chained to their vLEI which allows them to delegate authority to other persons or machines. + +As a reference example, we define a `vLEICardanoMetadataSigner` credential. For a given use-case, the issuee of this credential is allowed to sign transaction metadata on Cardano on behalf of a particular legal entity. The LEI of this legal entity is embedded in their Legal Entity vLEI credential. + +// TODO Diagram + +The above diagram contains 3 credentials which are cryptographically chained: +- **Qualified vLEI Issuer**: Issued by GLEIF to QVI entities. +- **Legal Entity vLEI**: Issued by a QVI to legal entities. +- **Cardano Metadata Signer**: Issued by the legal entity to a person or machine who may sign on behalf of the entity. + +The schema for the signer credential may be found here. It contains an attribute `labels` which is an array of metadata label numbers for which the signer has the authority to create verifiable records over. + +##### Establishment of signing authority +For this example, a signer controlling the identifier `EKtQ1lymrnrh3qv5S18PBzQ7ukHGFJ7EXkH7B22XEMIL` is holding a metadata signer credential valid for label `1447`. + +The following is the expected transaction format to publish the credential chain: +```JSON +{ + "????": + { + t: "AUTH_BEGIN", + s: “ED_GbUPpS8ZJEY-u8OB3QVe9C_CAFBdSimS5KxclkgWT”, + i: “EKtQ1lymrnrh3qv5S18PBzQ7ukHGFJ7EXkH7B22XEMIL”, + c: , + m: + { + l: [1447], + LEI: “50670047U83746F70E20” + } + } +} +```` +For ease of indexing, the metadata block is used to contain the LEI of the legal entity, as well as an array of all relevant metadata labels. As such, an indexer can filter based on interested metadata labels, or based on a particular set of legal entities. + +The credential chain `c` should be a qb2 CESR stream containing: +- Each ACDC credential and corresponding issuance event (`iss`) +- Registry events for each revocation registry (`vcp`) +- All necessary CESR attachments + +A test example may be found here in qb64 format - this should be converted to qb2 before being pushed on-chain. + +After verifying the validity of the credential chain with an ACDC verifier, there are a number of extra validation steps to complete as business logic: +1. `EKtQ1lymrnrh3qv5S18PBzQ7ukHGFJ7EXkH7B22XEMIL` is the issuee of the metadata signer credential. +2. The label attribute of the credential is `[1447]`. +3. The LEI attribute of the Legal Entity vLEI credential is `50670047U83746F70E20`. +4. The Qualified vLEI Issuer credential is issued by GLEIF’s External identifier, as listed [here](https://gleif-it.github.io/.well-known/). + +##### Creation of verifiable records +The following is an attestation transaction for metadata label `1447`. +```JSON +{ + "XXXX": { + “t”: “ATTEST”, + "i": “EKtQ1lymrnrh3qv5S18PBzQ7ukHGFJ7EXkH7B22XEMIL”, + “d”: “ELC5L3iBVD77d_MYbYGGCUQgqQBju1o4x1Ud-z2sL-ux”, + "s": “1a” + }, + “1447”: {} +} +``` + +Validation steps: +1. `EKtQ1lymrnrh3qv5S18PBzQ7ukHGFJ7EXkH7B22XEMIL` currently has signing authority over label 1447. +2. The CESR digest of the data at label 1447 is `ELC5L3iBVD77d_MYbYGGCUQgqQBju1o4x1Ud-z2sL-ux`. +3. The event in the controller’s KEL at sequence number `1a` (26th event) is `{ d: “ELC5L3iBVD77d_MYbYGGCUQgqQBju1o4x1Ud-z2sL-ux” }`. + +## Rationale: how does this CIP achieve its goals? + +## Path to Active + +## Appendix + +### Credential chains + +ACDCs can be chained together cryptographically in a similar manner to traditional X.509 certificate chains, yet with far more power and flexibility. + +For a given ecosystem, there may be a particular credential chain type that can be used to create bindings between controllers and entities or people. For example, in the vLEI ecosystem, credential chains may be used to create a binding between a legal entity and one of its employees that has the authority to sign transactions on its behalf. The root of trust in the vLEI ecosystem is GLEIF. + +### Identifying a credential chain type + +Various credential chain types may represent various forms of compliance or bindings so it's important to be able to differentiate between credential chain types so that chain indexers can more easily filter out irrelevant transactions. + +For this, the schema ID of the leaf credential in the credential chain may be used - that is, the credential which will be held by the person or software attesting to the metadata transaction. This is the strongest indicator of the credential chain type as child credential schemas reference parent credential schemas in a cryptographically strong manner. + +### Discovery via Out-of-Band-Introductions (OOBIs) + +In the context of this CIP, an OOBI provides a mechanism to discover verifiable information related to an identifier at an endpoint, such as the Key Event Log related to that identifier. All data is still verifiably signed, but a watcher network should be used to reduce the risk of discovering a forked, but verifiable version of a KEL. + +### Root of trust discovery + +GLEIF serves as the root of trust in the vLEI ecosystem. Discovery of their GLEIF Root identifier therefore must be carefully managed to avoid a Man-in-the-Middle attack where an attacker redirects a verifier to a different root identifier that is also verifiable. + +GLEIF has published their identifiers in various mediums such as various GitHub organizations, websites and hardcopy publications to mitigate the risk of an attacker compromising each medium, and [here](https://gleif-it.github.io/.well-known/) is one such location. The issuer of production QVI credentials is the GLEIF External, which is delegated from the GLEIF Root. + +## Copyright diff --git a/CIP-????/version_1.cddl b/CIP-????/version_1.cddl new file mode 100644 index 0000000000..825b1942dc --- /dev/null +++ b/CIP-????/version_1.cddl @@ -0,0 +1,35 @@ +cardano_keri_metadata = { + ? uint => auth_event +} + +auth_event = + auth_begin / + auth_end / + attest + +auth_begin = { + t: "AUTH_BEGIN", + s: text, ; SAID of leaf credential schema + i: text, ; AID of signer + c: bytes, ; Byte stream payload + ? m: metadata_map ; Optional metadata +} + +attest = { + t: "ATTEST", + i: text, ; AID of signer + d: text, ; Digest + s: text ; Hex-encoded sequence number +} + +auth_end = { + t: "AUTH_END", + s: text, ; SAID of leaf credential schema + i: text, ; AID of signer + c: bytes, ; Byte stream payload + ? m: metadata_map ; Optional metadata +} + +metadata_map = { + * text => any +} diff --git a/CIP-????/version_1.json b/CIP-????/version_1.json new file mode 100644 index 0000000000..e53bdb50c4 --- /dev/null +++ b/CIP-????/version_1.json @@ -0,0 +1,106 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "Cardano KERI Accountability Metadata", + "description": "Metadata schema for embedding KERI identifiers and authentication events (AUTH_BEGIN, ATTEST, AUTH_END) within Cardano transactions.", + "type": "object", + "patternProperties": { + "^[0-9]+$": { + "description": "Metadata label key (integer as string).", + "oneOf": [ + { + "type": "object", + "properties": { + "t": { + "const": "AUTH_BEGIN" + }, + "s": { + "type": "string", + "description": "Self-addressing identifier (SAID) of the leaf credential schema." + }, + "i": { + "type": "string", + "description": "Autonomic Identifier (AID) of the signer." + }, + "c": { + "type": "string", + "description": "Byte stream representing the credential or context." + }, + "m": { + "type": "object", + "description": "Optional metadata block.", + "additionalProperties": true + } + }, + "required": [ + "t", + "s", + "i", + "c" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "t": { + "const": "ATTEST" + }, + "i": { + "type": "string", + "description": "Autonomic Identifier (AID) of the signer." + }, + "d": { + "type": "string", + "description": "Digest referencing the authenticated data." + }, + "s": { + "type": "string", + "pattern": "^[0-9A-Fa-f]+$", + "description": "Hex-encoded sequence number." + } + }, + "required": [ + "t", + "i", + "d", + "s" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "t": { + "const": "AUTH_END" + }, + "s": { + "type": "string", + "description": "Self-addressing identifier (SAID) of the leaf credential schema." + }, + "i": { + "type": "string", + "description": "Autonomic Identifier (AID) of the signer." + }, + "c": { + "type": "string", + "description": "Byte stream representing the credential or closing context." + }, + "m": { + "type": "object", + "description": "Optional metadata block.", + "additionalProperties": true + } + }, + "required": [ + "t", + "s", + "i", + "c" + ], + "additionalProperties": false + } + ] + } + }, + "additionalProperties": false +} \ No newline at end of file From bb97df177e6435f627dc50057fb1d23b445c1f88 Mon Sep 17 00:00:00 2001 From: Kammerlo Date: Wed, 5 Nov 2025 08:00:26 +0100 Subject: [PATCH 16/31] chore: removed reeve cip draft --- CIP-1447/README.md | 202 ------------------- CIP-1447/version_1.1_onchain.cddl | 95 --------- CIP-1447/version_1.1_onchain.json | 311 ------------------------------ 3 files changed, 608 deletions(-) delete mode 100644 CIP-1447/README.md delete mode 100644 CIP-1447/version_1.1_onchain.cddl delete mode 100644 CIP-1447/version_1.1_onchain.json diff --git a/CIP-1447/README.md b/CIP-1447/README.md deleted file mode 100644 index 84f7640f78..0000000000 --- a/CIP-1447/README.md +++ /dev/null @@ -1,202 +0,0 @@ ---- -CIP: 1447 -Title: On-chain financial transactions -Category: Metadata -Status: Proposed -Authors: - - Thomas Kammerlocher - - Mateusz Czeladka -Implementors: - - Reeve: https://github.com/cardano-foundation/cf-reeve-platform -Discussions: - - -Created: 2025-07-17 -License: CC-BY-4.0 ---- - -# Abstract - -The need for transparency of organisations and legal entities continues to grow as a cornerstone of trust. This demand especially includes the need for transparency of financial transactions of these entities to prove they are fulfilling their purpose. - -This Cardano Improvement Proposal (CIP) introduces a standardized method for anchoring both single financial transactions and custom organisational reports into transaction metadata, leveraging the blockchain as an immutable and publicly verifiable layer of trust. -The proposed standard is designed to be easily intelligible, allowing auditors, stakeholders, and the public to both trace individual transactions and analyze aggregated custom reports, creating a holistic and unalterable financial picture for any entity. -To ensure its long-term viability and adoption, the CIP also outlines a self-sustaining model to support ongoing development and maintenance of the standard, establishing Cardano as the premier infrastructure for organisational financial accountability. - -# Motivation: Why this CIP is necessary? - -True transparency is achieved not by merely publishing data, but by ensuring it is structured in a way that is universally understandable and interpretable for everyone. -Without a common standard, on-chain financial data remains cryptic to most, failing to build the trust it promises. - -This CIP aims to provide this explanation to enable everyone to understand the financial transactions and reports of organisations and thus bringing real transparency and enhancing trust of organisations willing to share their financial data on-chain. -To achieve this, the format must be as easy as possible to read and understand for humans, while still being machine-readable to allow for automated processing. - -**This readability comes with a price:** the format is not as compact as it could be, but this is a trade-off that is worth making to achieve the goal of transparency. - -However, this is a necessary investment in universal accessibility and long-term trust. -It ensures that any person, from an accountant to a stakeholder, can view the raw data on a block explorer and understand it immediately, without needing specialized software. -This approach guarantees that the financial records remain transparent and independently verifiable, ensuring their value and integrity persist even if the application used to publish them shuts down. - -# Specification - -This proposal defines how to structure metadata to anchor financial transactions and reports on-chain, ensuring they are both human-readable and machine-interpretable. -These metadata can be attached to any transaction. -The target of this metadata is to ensure flexibility for organisations. Reports differ between organisations, since they have different purposes, structures, and reporting periods. -The metadata structure is designed to be extensible, allowing for future enhancements without breaking existing implementations. - -## General structure - -The general structure contains the base information of the organisation, the metadata version, and the type of these financial records. -The json structure is as follows: -```json -"1447": { - "org": { - "id": "string", // SHA3-256 hash of :: - "name": "string", // Name of the organisation - "currency_id": "string", // ISO 4217 currency code of the organisation - "country_code": "string" // ISO 3166-1 alpha-2 country code of the organisation - "tax_id_number": "string" // tax identification number of the organisation - }, - "metadata": { - "version": "string" // Version of the metadata format - }, - "type": "string", // Type of the metadata - "data": // data object is defined through the Type of the metadata -} -``` - -The type can have two values: -- `INDIVIDUAL_TRANSACTIONS`: This type is used to anchor individual financial transactions of the organisation. -- `REPORT`: This type is used to anchor a custom report of the organisation - -### Individual Transactions -Additionally to the general structure the type `INDIVIDUAL_TRANSACTIONS` stores the individual accounting transactions of the organisation within the data object. - -Required fields: - -| Field | Type | Description | -|----------|--------|----------------------------------------------------------------------------------------------------------------------------------------| -| `id` | string | Unique identifier for the organisation, SHA3-256 hash of organisation ID and the transactionn number (e.g., "::") | -| `number` | string | Unique identifier for the transaction given from the accounting system used for identifying the transaction | -| `type` | enum | Type of the transaction represented as an enum to limit the space. The list of specific transactions types can be extended. | -| `date` | string | Date of the transaction in ISO 8601 format (YYYY-MM-DD) | -| `items` | array | Array of items in the transaction, each item represents an event and can have additional fields like event, project, cost center, etc. | - -The list of possible transactions type is to be extended, but the following types are defined as a starting point: - -| Type | Description | -|-------------------|----------------------------------------------------------------------------------------------| -| `Journal` | General journal entry, used for recording various financial transactions | -| `VendorBill` | Bill from a vendor, representing an amount owed to a supplier | -| `VendorPayment` | Payment made to a vendor, reducing the amount owed to them | -| `CustomerInvoice` | Invoice issued to a customer, representing an amount owed by them | -| `CustomerPayment` | Payment received from a customer, reducing the amount owed by them | -| `BILL_CREDIT` | Credit note issued against a vendor bill, reducing the amount owed to the vendor | -| `CARD_CHARGE` | Charge made to a credit card, representing an expense incurred by the organisation | -| `CARD_REFUND` | Refund issued to a credit card, representing a return of funds to the organisation's card | -| `FX_REVALUATION` | Foreign exchange revaluation, used to adjust the value of foreign currency transactions | -| `TRANSFER` | Transfer of funds between accounts, representing a movement of money within the organisation | -| `EXPENSE_REPORT` | Report of expenses incurred by employees, summarizing various costs and reimbursements | - -Additional fields can be added to the data object, such as accounting period, custom id, etc. - -#### Transaction Items -Items are the individual financial entries within the transaction. Each item can have the following fields: - -| Field | Type | Description | -|----------------|--------|----------------------------------------------------------------------------------------------------------------------| -| `id` | string | Unique identifier for the item, SHA3-256 hash of the transaction id and the item number | -| `amount` | string | Monetary amount of the transaction item, in the item currency | -| `fx_rate` | string | Foreign exchange rate on effect at the date of the transaction, that converts the amount to the functional currency. | -| `document` | object | Document details related to the transaction item, can include number, currency, event, project, cost center, etc. | -| `event` | object | Event details related to the transaction item, can include code and name | -| `project` | object | Optional project details related to the transaction item, can include cust_code and name | -| `cost_center` | object | Optional cost center details related to the transaction item, can include cust_code and name | -| `vat` | object | Optional VAT details related to the transaction item, can include cust_code and rate | -| `counterparty` | object | Optional counterparty details related to the transaction item, can include cust_code and type | - -Example json -```json -{ - , - "type": "INDIVIDUAL_TRANSACTIONS", - "data": [ - { - "id": "string", // SHA3-256 hash of :: - "number": "Transaction123", - "type": "JOURNAL", - "date": "2025-01-01", - "accounting_period": "2025-12", - "items": [ - { - "id": "string", // SHA3-256 hash of :: - "amount": "2874", - "fx_rate": "0.93", - "document": { - "number": "JE-5810", - "currency": { - "id": "ISO_4217:EUR", - "cust_code": "EUR" - } - }, - "cost_center": { - "cust_code": "1000", - "name": "Internal Operations" - } - } - ] - } - ] -} -``` - -### Report -The type `REPORT` is used to publish reports of organisation. These reports can be highly customized resulting in the need for a flexible and adjustable structure. - -Required fields: - -| Field | Type | Description | -|-------------|-----------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `interval` | string | The reporting interval, e.g., "YEARLY", "QUARTERLY", "MONTHLY", etc. | -| `year` | string | The year of the report, e.g., "2025". | -| `period` | integer | The period of the report according to the interval, e.g., if Monthly 1 for January, 2 for February, if quarterly 1 for Q1, 2 for Q2 | -| `subtype` | string | Definition of what of the report type - Organisations can have custom reports, e.g., "BALANCE_SHEET", "INCOME_STATEMENT" | -| `data` | anyOf [string, data object] | The actual report data, which can be highly customized and structured according to the organisation's needs. This object should repesent categories and subcategories. | - -#### Example json: - -```json -{ - , - "type": "REPORT", - "interval": "MONTHLY", - "year": "2025", - "period": 12, - "subtype": "BALANCE_SHEET", - "data": { - "assets": { - "current_assets": { - "cash": "1000" - }, - "non_current_assets": { - "property": "5000" - } - }, - "liabilities": { - "current_liabilities": { - "accounts_payable": "200" - }, - "non_current_liabilities": { - "long_term_debt": "1000" - } - } - } -} -``` - -# Glossary -Since some terms within this CIP require specific definitions to ensure clarity and consistency, the following glossary is provided: -- **Cost Center**: A department or function within an organization that incurs costs but does not directly generate profit (e.g., the IT or Human Resources department). It is used for internal cost tracking. -- **Counterparty**: The other party that participates in a financial transaction. For example, in a sales transaction, the customer is the counterparty to the seller. -- **Foreign Exchange (FX) Rate**: The rate at which one currency can be exchanged for another. It is used when a transaction involves multiple currencies. -- **Value-Added Tax (VAT)**: A consumption tax placed on a product whenever value is added at each stage of the supply chain, from production to the point of sale. -- **Document**: A formal record of a transaction, which can include invoices, receipts, or other financial documents that provide evidence of the transaction. \ No newline at end of file diff --git a/CIP-1447/version_1.1_onchain.cddl b/CIP-1447/version_1.1_onchain.cddl deleted file mode 100644 index d3b9320acb..0000000000 --- a/CIP-1447/version_1.1_onchain.cddl +++ /dev/null @@ -1,95 +0,0 @@ -; Main entry point for the financial data structure -; The top-level key is a transaction metadata label, represented as an integer. -financial_data = { - * uint => cipBody -} - -; The main body of the CIP data, which can be one of two types. -cipBody = { - org: organisation, - metadata: metadataInfo, - ( report / individualTransactions ) -} - -; -- Organisation and Metadata Definitions -- - -organisation = { - id: tstr .regexp "^[a-fA-F0-9]{64}$", ; SHA3-256 hash - name: tstr, - currency_id: tstr .regexp "^ISO_4217:[A-Z]{3}$", - country_code: tstr .regexp "^[A-Z]{2}$", - tax_id_number: tstr, -} - -metadataInfo = { - version: tstr, -} - -; -- Report Type Definition -- - -report = { - type: "REPORT", - interval: tstr, - year: tstr .regexp "^[12][0-9]{3}$", - period: uint, - subtype: tstr, - data: (tstr / recursiveObject), - * tstr => any ; Allows for additional, non-specified properties -} - -; -- Individual Transactions Type Definition -- - -individualTransactions = { - type: "INDIVIDUAL_TRANSACTIONS", - data: [+ transaction] ; Array of one or more transactions -} - -transaction = { - id: tstr .regexp "^[a-fA-F0-9]{64}$", ; SHA3-256 hash - number: tstr, - type: tstr, - date: tstr, ; Should conform to ISO 8601 date format, e.g., "YYYY-MM-DD" - items: [+ lineItem], - * tstr => any ; Allows for additional properties like 'accounting_period' -} - -lineItem = { - id: tstr, - amount: tstr, - fx_rate: tstr, - document: document, - ? event: eventDetail, - ? project: classificationDetail, - ? cost_center: classificationDetail, - ? vat: classificationDetail, - ? counterparty: classificationDetail, - * tstr => any ; Allows for additional, non-specified properties -} - -; -- Reusable Component Definitions -- - -document = { - number: tstr, - currency: currency, -} - -currency = { - cust_code: tstr, - id: tstr .regexp "^ISO_4217:[A-Z]{3}$", -} - -eventDetail = { - code: tstr, - name: tstr, -} - -; A reusable structure for dimensional data like project, cost center, etc. -classificationDetail = { - cust_code: tstr, - name: tstr, -} - -; A recursive structure for nested report data (e.g., categories/subcategories) -recursiveObject = { - * tstr => (tstr / recursiveObject) -} diff --git a/CIP-1447/version_1.1_onchain.json b/CIP-1447/version_1.1_onchain.json deleted file mode 100644 index 47f8f2dd1b..0000000000 --- a/CIP-1447/version_1.1_onchain.json +++ /dev/null @@ -1,311 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "title": "CIP Financial Data Standard", - "description": "A schema for anchoring financial transactions and reports on-chain, based on the specified CIP format.", - "type": "object", - "patternProperties": { - "^[0-9]+$": { - "$ref": "#/definitions/cipBody" - } - }, - "additionalProperties": false, - "definitions": { - "cipBody": { - "type": "object", - "properties": { - "org": { - "$ref": "#/definitions/organisation" - }, - "metadata": { - "$ref": "#/definitions/metadataInfo" - } - }, - "oneOf": [ - { - "$ref": "#/definitions/report" - }, - { - "$ref": "#/definitions/individualTransactions" - } - ], - "required": [ - "org", - "metadata" - ], - "additionalProperties": false - }, - "organisation": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "SHA3-256 hash of ::.", - "pattern": "^[a-fA-F0-9]{64}$" - }, - "name": { - "type": "string", - "description": "Name of the organisation." - }, - "currency_id": { - "type": "string", - "description": "Default currency of the organisation, formatted as ISO_4217:.", - "pattern": "^ISO_4217:[A-Z]{3}$" - }, - "country_code": { - "type": "string", - "description": "ISO 3166-1 alpha-2 country code of the organisation.", - "pattern": "^[A-Z]{2}$" - }, - "tax_id_number": { - "type": "string", - "description": "Tax identification number of the organisation." - } - }, - "required": [ - "id", - "name", - "currency_id", - "country_code", - "tax_id_number" - ], - "additionalProperties": true - }, - "metadataInfo": { - "type": "object", - "properties": { - "version": { - "type": "string", - "description": "Version of the metadata format." - } - }, - "required": [ - "version" - ] - }, - "report": { - "type": "object", - "properties": { - "type": { - "const": "REPORT" - }, - "interval": { - "type": "string", - "description": "The reporting interval, e.g., 'YEARLY', 'QUARTERLY', 'MONTHLY'." - }, - "year": { - "type": "string", - "description": "The four-digit year of the report.", - "pattern": "^[12][0-9]{3}$" - }, - "period": { - "type": "integer", - "description": "The period of the report according to the interval.", - "minimum": 1 - }, - "subtype": { - "type": "string", - "description": "The specific type of report, e.g., 'BALANCE_SHEET'." - }, - "data": { - "description": "Custom report data, which can be a simple string or a nested object representing categories and subcategories.", - "anyOf": [ - { - "type": "string" - }, - { - "$ref": "#/definitions/recursiveObject" - } - ] - } - }, - "required": [ - "type", - "interval", - "year", - "period", - "subtype", - "data" - ], - "additionalProperties": true - }, - "individualTransactions": { - "type": "object", - "properties": { - "type": { - "const": "INDIVIDUAL_TRANSACTIONS" - }, - "data": { - "type": "array", - "items": { - "$ref": "#/definitions/transaction" - } - } - }, - "required": [ - "type", - "data" - ], - "additionalProperties": false - }, - "transaction": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "SHA3-256 hash of ::.", - "pattern": "^[a-fA-F0-9]{64}$" - }, - "number": { - "type": "string" - }, - "type": { - "type": "string" - }, - "date": { - "type": "string", - "format": "date" - }, - "items": { - "type": "array", - "items": { - "$ref": "#/definitions/lineItem" - }, - "minItems": 1 - } - }, - "required": [ - "id", - "number", - "type", - "date", - "items" - ], - "additionalProperties": true - }, - "lineItem": { - "type": "object", - "properties": { - "id": { - "type": "string" - }, - "amount": { - "type": "string" - }, - "fx_rate": { - "type": "string" - }, - "document": { - "$ref": "#/definitions/document" - }, - "event": { - "$ref": "#/definitions/eventDetail" - }, - "project": { - "$ref": "#/definitions/classificationDetail" - }, - "cost_center": { - "$ref": "#/definitions/classificationDetail" - }, - "vat": { - "$ref": "#/definitions/classificationDetail" - }, - "counterparty": { - "$ref": "#/definitions/classificationDetail" - } - }, - "required": [ - "id", - "amount", - "fx_rate", - "document" - ], - "additionalProperties": true - }, - "eventDetail": { - "type": "object", - "description": "Details about the event associated with the transaction, such as code and name.", - "properties": { - "code": { - "type": "string", - "description": "Event code, e.g., '71103100'." - }, - "name": { - "type": "string", - "description": "Name of the event, e.g., 'Payroll Expenses - Salaries and wages/Accounts payable'." - } - }, - "required": [ - "code", - "name" - ] - }, - "classificationDetail": { - "type": "object", - "description": "Details for classification such as project, cost center, VAT, or counterparty.", - "properties": { - "cust_code": { - "type": "string", - "description": "Custom code for the classification, e.g., '9000' for cost center." - }, - "name": { - "type": "string", - "description": "Name of the classification, e.g., 'Internal' for cost center." - } - }, - "required": [ - "cust_code", - "name" - ] - }, - "document": { - "type": "object", - "description": "A formal record of a transaction, which can include invoices, receipts", - "properties": { - "number": { - "type": "string", - "description": "Document number or identifier." - }, - "currency": { - "$ref": "#/definitions/currency" - } - }, - "required": [ - "number", - "currency" - ] - }, - "currency": { - "type": "object", - "description": "Currency information, formatted as ISO_4217:.", - "properties": { - "cust_code": { - "type": "string", - "description": "Custom code for the currency, e.g., 'USD'." - }, - "id": { - "type": "string", - "description": "Currency identifier, formatted as ISO_4217:.", - "pattern": "^ISO_4217:[A-Z]{3}$" - } - }, - "required": [ - "cust_code", - "id" - ] - }, - "recursiveObject": { - "type": "object", - "description": "A flexible object for categories and subcategories where each value can be a string or another nested object.", - "additionalProperties": { - "anyOf": [ - { - "type": "string" - }, - { - "$ref": "#/definitions/recursiveObject" - } - ] - } - } - } -} \ No newline at end of file From fe4ccf3dad619198483108aecf9aaaa01b1cf557 Mon Sep 17 00:00:00 2001 From: Kammerlo Date: Wed, 5 Nov 2025 08:03:51 +0100 Subject: [PATCH 17/31] docs: adjusted placeholders in markdown --- CIP-????/README.md | 58 +++++++++++++++++++++++----------------------- 1 file changed, 29 insertions(+), 29 deletions(-) diff --git a/CIP-????/README.md b/CIP-????/README.md index 9922cd9f8b..76ae79ac88 100644 --- a/CIP-????/README.md +++ b/CIP-????/README.md @@ -64,11 +64,11 @@ The metadata is structured as follows: { "????": { - t: "AUTH_BEGIN", - s: , - i: , - c: , - m: + "t": "AUTH_BEGIN", + "s": "{{saidOfLeafCredentialSchema}}", + "i": "{{aidOfSigner}}", + "c": "{{byteStream}}", + "m": "{{optionalMetadataBlock}}" } } ``` @@ -82,17 +82,17 @@ To create a persistent signature over data with KERI, signers can anchor a diges - **i** — The identifier of the signer in the CESR qb64 variant. - **d** — The digest of the data being signed in the CESR qb64 variant. - **s** — The sequence number of the KERI event, encoded as a hex string. -If the KEL of identifier `i` contains an event at sequence number `s` which has a seal value of `{ d: }`, it serves as cryptographically verifiable proof that the data was effectively signed by the controller. +If the KEL of identifier `i` contains an event at sequence number `s` which has a seal value of `{ d: "{{digest}}" }`, it serves as cryptographically verifiable proof that the data was effectively signed by the controller. A reference to this event in a metadata transaction is structured as follows: ```JSON { "????": { - "i": , - “d”: , - "s": , - “t”: “ATTEST” + "t": "ATTEST", + "i": "{{aidOfSigner}}", + "d": "{{digest}}", + "s": "{{hexEncodedSequenceNumber}}" }, - “YYYY”: {} // Metadata i can sign + "YYYY": "{{someApplicationMetadata}}" } ``` Such transactions are only considered valid if the digest value is correct, and can be found anchored in the KEL of the controller at the given sequence number. @@ -111,11 +111,11 @@ A reference to this event in a metadata transaction is structured as follows: { "????": { - t: "AUTH_END", - s: , - i: , - c: , - m: + "t": "AUTH_END", + "s": "{{saidOfLeafCredentialSchema}}", + "i": "{{aidOfSigner}}", + "c": "{{byteStream}}", + "m": "{{optionalMetadataBlock}}" } } @@ -148,18 +148,18 @@ The following is the expected transaction format to publish the credential chain { "????": { - t: "AUTH_BEGIN", - s: “ED_GbUPpS8ZJEY-u8OB3QVe9C_CAFBdSimS5KxclkgWT”, - i: “EKtQ1lymrnrh3qv5S18PBzQ7ukHGFJ7EXkH7B22XEMIL”, - c: , - m: + "t": "AUTH_BEGIN", + "s": "ED_GbUPpS8ZJEY-u8OB3QVe9C_CAFBdSimS5KxclkgWT", + "i": "EKtQ1lymrnrh3qv5S18PBzQ7ukHGFJ7EXkH7B22XEMIL", + "c": "{{credentialChainByteStream}}", + "m": { - l: [1447], - LEI: “50670047U83746F70E20” + "l": [1447], + "LEI": "50670047U83746F70E20" } } } -```` +``` For ease of indexing, the metadata block is used to contain the LEI of the legal entity, as well as an array of all relevant metadata labels. As such, an indexer can filter based on interested metadata labels, or based on a particular set of legal entities. The credential chain `c` should be a qb2 CESR stream containing: @@ -180,12 +180,12 @@ The following is an attestation transaction for metadata label `1447`. ```JSON { "XXXX": { - “t”: “ATTEST”, - "i": “EKtQ1lymrnrh3qv5S18PBzQ7ukHGFJ7EXkH7B22XEMIL”, - “d”: “ELC5L3iBVD77d_MYbYGGCUQgqQBju1o4x1Ud-z2sL-ux”, - "s": “1a” + "t": "ATTEST", + "i": "EKtQ1lymrnrh3qv5S18PBzQ7ukHGFJ7EXkH7B22XEMIL", + "d": "ELC5L3iBVD77d_MYbYGGCUQgqQBju1o4x1Ud-z2sL-ux", + "s": "1a" }, - “1447”: {} + "1447": "{{someApplicationMetadata}}" } ``` From ad492a5d8576dce31cec5ae0f942a3a7bf7846ca Mon Sep 17 00:00:00 2001 From: Kammerlo Date: Wed, 5 Nov 2025 11:24:46 +0100 Subject: [PATCH 18/31] docs: added linebreaks for better readability --- CIP-????/README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/CIP-????/README.md b/CIP-????/README.md index 76ae79ac88..5a5df065c0 100644 --- a/CIP-????/README.md +++ b/CIP-????/README.md @@ -18,20 +18,26 @@ License: CC-BY-4.0 ## Abstract Accountability is essential for legal entities, organizations, and authorities operating in regulated environments. To establish accountability on the Cardano blockchain, it must be possible to prove the identity of entities responsible for on-chain actions in a verifiable and interoperable way. + This CIP defines a standardized mechanism to embed KERI (Key Event Receipt Infrastructure) identifiers within Cardano transaction metadata. KERI provides self-certifying, portable, and decentralized identifiers known as Autonomic Identifiers (AIDs) that can be anchored to various roots of trust—such as verifiable Legal Entity Identifiers (vLEIs), organizational registries, or domain-specific trust frameworks. + By including KERI identifiers in transaction metadata, Cardano enables a flexible, trust-agnostic approach to identity binding. This approach supports accountability, legal and regulatory compliance, and interoperability with existing and emerging global identity ecosystems, while remaining compatible with self-sovereign identity principles. ## Motivation: why is this CIP necessary? The need for auditable and verifiable identifiers is rising, as accountability, traceability, and transparency are essential pillars in regulated environments. Without a standardized mechanism, it is difficult to reliably link on-chain activity to persistent and legally recognized identities. + KERI (Key Event Receipt Infrastructure) addresses this challenge by providing a decentralized, key-oriented identifier system for secure, portable, and self-certifying digital identities. Rather than relying on centralized registries, KERI establishes identifiers through cryptographic event logs, enabling secure key rotation, continuity of control, and tamper-evident audit trails. This ensures that an identifier can consistently represent the same entity over time, while also being interoperable with verifiable credentials and root of trusts such as vLEIs. + By embedding KERI identifiers into Cardano transaction metadata, we create a standardized, verifiable connection between on-chain actions and off-chain accountability frameworks. This allows transactions to be cryptographically tied to a specific identifier and, through credential chains also published on-chain, to a legally recognized entity. ## Specification Below we define a generic solution to enable metadata signing where a particular ecosystem or use-case may leverage a root of trust of its choosing – each most likely with its own credential chain format. + The credentials used in the KERI ecosystem are known as ACDCs, or [Authentic Chained Data Containers](https://www.rfc-editor.org/rfc/rfc8174). This CIP will not explain at depth how KERI and ACDCs work due to their technical complexity. The appendix will however include some expanded explanations to help provide clarity. + Beyond the specification and as a useful reference, we will outline how credential chains for the vLEI ecosystem can be leveraged to provide high assurance to [Reeve](https://reeve.technology). > [!NOTE] From 13e47829756cc54fddc501a16d9fcb3aea90a88a Mon Sep 17 00:00:00 2001 From: Kammerlo Date: Thu, 6 Nov 2025 07:55:06 +0100 Subject: [PATCH 19/31] docs: updated texts, removed todos, added diagrams --- CIP-????/README.md | 69 ++++++++++++++++++++++++++++++++++++---------- 1 file changed, 54 insertions(+), 15 deletions(-) diff --git a/CIP-????/README.md b/CIP-????/README.md index 5a5df065c0..73a8f41012 100644 --- a/CIP-????/README.md +++ b/CIP-????/README.md @@ -25,34 +25,59 @@ By including KERI identifiers in transaction metadata, Cardano enables a flexibl ## Motivation: why is this CIP necessary? -The need for auditable and verifiable identifiers is rising, as accountability, traceability, and transparency are essential pillars in regulated environments. Without a standardized mechanism, it is difficult to reliably link on-chain activity to persistent and legally recognized identities. +The demand for auditable and verifiable identifiers is increasing as accountability, traceability, and transparency become fundamental requirements for entities operating within regulated environments. Without a standardized mechanism, it is difficult to reliably associate on-chain activity with persistent and legally recognized identities. -KERI (Key Event Receipt Infrastructure) addresses this challenge by providing a decentralized, key-oriented identifier system for secure, portable, and self-certifying digital identities. Rather than relying on centralized registries, KERI establishes identifiers through cryptographic event logs, enabling secure key rotation, continuity of control, and tamper-evident audit trails. This ensures that an identifier can consistently represent the same entity over time, while also being interoperable with verifiable credentials and root of trusts such as vLEIs. +KERI (Key Event Receipt Infrastructure) addresses this challenge by introducing a decentralized, key-oriented identifier system that supports secure, portable, and self-certifying digital identities. Instead of relying on centralized registries, KERI establishes identifiers through cryptographically verifiable event logs, enabling secure key rotation, continuity of control, and tamper-evident auditability. This approach ensures that an identifier can consistently represent the same entity over time, while remaining interoperable with verifiable credentials and roots of trust such as verifiable Legal Entity Identifiers (vLEIs). -By embedding KERI identifiers into Cardano transaction metadata, we create a standardized, verifiable connection between on-chain actions and off-chain accountability frameworks. This allows transactions to be cryptographically tied to a specific identifier and, through credential chains also published on-chain, to a legally recognized entity. +By embedding KERI identifiers into Cardano transaction metadata, this proposal enables a standardized and verifiable linkage between on-chain actions and off-chain accountability frameworks. This allows transactions to be cryptographically bound to a specific identifier and, through verifiable credential chains, to a legally recognized entity, thereby enhancing trust and compliance across decentralized and regulated ecosystems. ## Specification -Below we define a generic solution to enable metadata signing where a particular ecosystem or use-case may leverage a root of trust of its choosing – each most likely with its own credential chain format. +Below a generic solution is defined to enable metadata signing where a particular ecosystem or use-case may leverage a root of trust of its choosing – each most likely with its own credential chain format. -The credentials used in the KERI ecosystem are known as ACDCs, or [Authentic Chained Data Containers](https://www.rfc-editor.org/rfc/rfc8174). This CIP will not explain at depth how KERI and ACDCs work due to their technical complexity. The appendix will however include some expanded explanations to help provide clarity. - -Beyond the specification and as a useful reference, we will outline how credential chains for the vLEI ecosystem can be leveraged to provide high assurance to [Reeve](https://reeve.technology). +The credentials used in the KERI ecosystem are known as ACDCs, or [Authentic Chained Data Containers](https://www.rfc-editor.org/rfc/rfc8174). This CIP will not explain at depth how KERI and ACDCs work due to their technical complexity. The [Appendix](#appendix) will however include some expanded explanations to help provide clarity. > [!NOTE] > The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119](https://www.rfc-editor.org/rfc/rfc2119) [RFC8174](https://www.rfc-editor.org/rfc/rfc8174) when, and only when, they appear in all capitals, as shown here. ### Key Event Log Discovery - In order to verify the validity of credential chains and metadata transactions, Key Event Logs, or KELs, for all issuing and holding identifiers in the credential chain must be made available to a verifier. KELs may live off-chain for interoperability and scalability reasons, so this CIP does not make assumptions on which medium the KELs are published. A KERI watcher network SHOULD be used to discover up-to-date KELs for a given identifier for certain security reasons. Discovery of the watcher network relevant to a given ecosystem depends on the ecosystem itself. -However, as KERI is a maturing technology, wide-spread deployment of watcher networks is not yet guaranteed. Until then, the interim solution is to publish an Out-of-Band-Introduction to this Github repository for discovery, and this may be used by a verifier to discover and query for KEL events and updates. +However, as KERI is a maturing technology, wide-spread deployment of watcher networks is not yet guaranteed. Until then, the interim solution is to publish an [Out-of-Band-Introduction](#discovery-via-out-of-band-introductions-oobis) via a known persistent channel for the specific project for discovery, and this may be used by a verifier to discover and query for KEL events and updates. In one way or another, chain indexers must query for Key Event Log updates to validate credential chains and metadata transactions during the process of verification. +### Visualized Identity Lifecycle +The following diagram illustrates the lifecycle of signing authority for a KERI identifier on Cardano. It demonstrates how [attestations](#creation-of-verifiable-records) are invalid before [authority is established](#establishment-of-signing-authority) (`AUTH_BEGIN`), become valid during the authenticated period, and become invalid again after [revocation](#removal-of-signing-authority) (`AUTH_END`). The indexer validates each transaction by checking the current state of the credential chain. + +```mermaid +--- +config: + theme: redux +--- +sequenceDiagram + participant Legal Entity as Legal Entity + participant Cardano as Cardano + participant Indexer as Indexer + Legal Entity ->> Cardano: ATTEST + Cardano ->> Indexer: Identity invalid + Note right of Indexer: ❌ No valid credential + Legal Entity ->> Cardano: AUTH_BEGIN + Cardano ->> Indexer: Credential known + Note right of Indexer: ✅ Identifier established + Legal Entity ->> Cardano: ATTEST + Cardano ->> Indexer: Identity verified + Note right of Indexer: ✅ Valid signature + Legal Entity ->> Cardano: AUTH_END + Cardano ->> Indexer: Credential revoked + Note right of Indexer: ⚠️ Identifier revoked + Legal Entity ->> Cardano: ATTEST + Cardano ->> Indexer: Identity invalid + Note right of Indexer: ❌ No valid credential +``` ### Establishment of signing authority Before attesting to any transactions, the relevant credential chain for the controller must be published on-chain with the following attributes – most of which are used to help simplify indexing: - **t** — A transaction type of `AUTH_BEGIN` is used to establish a signer’s authority using a credential chain. @@ -103,7 +128,7 @@ A reference to this event in a metadata transaction is structured as follows: ``` Such transactions are only considered valid if the digest value is correct, and can be found anchored in the KEL of the controller at the given sequence number. -### Removal of signing authority +### Revoking of signing authority Signing authority may be removed after a period of time by revoking the relevant credential and publishing this revocation on-chain. As such, the validity of transactions associated with that credential chain are for all valid `ATTEST` transactions between issuance (`AUTH_BEGIN`) and revocation (`AUTH_END`). The following attributes are used: @@ -137,7 +162,25 @@ Legal entities holding valid vLEI credentials may issue other credentials chaine As a reference example, we define a `vLEICardanoMetadataSigner` credential. For a given use-case, the issuee of this credential is allowed to sign transaction metadata on Cardano on behalf of a particular legal entity. The LEI of this legal entity is embedded in their Legal Entity vLEI credential. -// TODO Diagram +```mermaid +graph LR + GLEIF["GLEIF Root
(Root of Trust)"] + QVI["Qualified vLEI Issuer
Credential"] + LE["Legal Entity vLEI
Credential
(contains LEI)"] + SIGNER["Cardano Metadata Signer
Credential
(contains metadata labels)"] + + GLEIF -->|issues| QVI + QVI -->|issues| LE + LE -->|issues| SIGNER + + SIGNER -.->|signs metadata
transactions on| CARDANO["Cardano Blockchain"] + + style GLEIF fill:#e1f5ff,stroke:#0066cc,stroke-width:2px + style QVI fill:#fff4e1,stroke:#cc8800,stroke-width:2px + style LE fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px + style SIGNER fill:#fce4ec,stroke:#c2185b,stroke-width:2px + style CARDANO fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px +``` The above diagram contains 3 credentials which are cryptographically chained: - **Qualified vLEI Issuer**: Issued by GLEIF to QVI entities. @@ -200,10 +243,6 @@ Validation steps: 2. The CESR digest of the data at label 1447 is `ELC5L3iBVD77d_MYbYGGCUQgqQBju1o4x1Ud-z2sL-ux`. 3. The event in the controller’s KEL at sequence number `1a` (26th event) is `{ d: “ELC5L3iBVD77d_MYbYGGCUQgqQBju1o4x1Ud-z2sL-ux” }`. -## Rationale: how does this CIP achieve its goals? - -## Path to Active - ## Appendix ### Credential chains From 1b26e712ce15f62a836060ecb138971a4ff0117b Mon Sep 17 00:00:00 2001 From: Kammerlo Date: Thu, 6 Nov 2025 07:56:03 +0100 Subject: [PATCH 20/31] docs: updated texts, removed todos, added diagrams --- CIP-????/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CIP-????/README.md b/CIP-????/README.md index 73a8f41012..bba6b85988 100644 --- a/CIP-????/README.md +++ b/CIP-????/README.md @@ -51,7 +51,7 @@ However, as KERI is a maturing technology, wide-spread deployment of watcher net In one way or another, chain indexers must query for Key Event Log updates to validate credential chains and metadata transactions during the process of verification. ### Visualized Identity Lifecycle -The following diagram illustrates the lifecycle of signing authority for a KERI identifier on Cardano. It demonstrates how [attestations](#creation-of-verifiable-records) are invalid before [authority is established](#establishment-of-signing-authority) (`AUTH_BEGIN`), become valid during the authenticated period, and become invalid again after [revocation](#removal-of-signing-authority) (`AUTH_END`). The indexer validates each transaction by checking the current state of the credential chain. +The following diagram illustrates the lifecycle of signing authority for a KERI identifier on Cardano. It demonstrates how [attestations](#creation-of-verifiable-records) (`ATTEST`) are invalid before [authority is established](#establishment-of-signing-authority) (`AUTH_BEGIN`), become valid during the authenticated period, and become invalid again after [revocation](#removal-of-signing-authority) (`AUTH_END`). The indexer validates each transaction by checking the current state of the credential chain. ```mermaid --- From 0bc2645f9a0aac2e6fd2024c687774147bd57884 Mon Sep 17 00:00:00 2001 From: Kammerlo Date: Thu, 6 Nov 2025 07:57:05 +0100 Subject: [PATCH 21/31] docs: added copyright --- CIP-????/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CIP-????/README.md b/CIP-????/README.md index bba6b85988..00486425b8 100644 --- a/CIP-????/README.md +++ b/CIP-????/README.md @@ -268,3 +268,5 @@ GLEIF serves as the root of trust in the vLEI ecosystem. Discovery of their GLEI GLEIF has published their identifiers in various mediums such as various GitHub organizations, websites and hardcopy publications to mitigate the risk of an attacker compromising each medium, and [here](https://gleif-it.github.io/.well-known/) is one such location. The issuer of production QVI credentials is the GLEIF External, which is delegated from the GLEIF Root. ## Copyright + +This CIP is licensed under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode) \ No newline at end of file From b160e25e0c90981d819f9b34ec8d0fa9d68a0907 Mon Sep 17 00:00:00 2001 From: Kammerlo Date: Fri, 7 Nov 2025 14:32:51 +0100 Subject: [PATCH 22/31] docs: some feedback incorporated --- CIP-????/README.md | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/CIP-????/README.md b/CIP-????/README.md index 00486425b8..49d749c730 100644 --- a/CIP-????/README.md +++ b/CIP-????/README.md @@ -19,7 +19,7 @@ License: CC-BY-4.0 Accountability is essential for legal entities, organizations, and authorities operating in regulated environments. To establish accountability on the Cardano blockchain, it must be possible to prove the identity of entities responsible for on-chain actions in a verifiable and interoperable way. -This CIP defines a standardized mechanism to embed KERI (Key Event Receipt Infrastructure) identifiers within Cardano transaction metadata. KERI provides self-certifying, portable, and decentralized identifiers known as Autonomic Identifiers (AIDs) that can be anchored to various roots of trust—such as verifiable Legal Entity Identifiers (vLEIs), organizational registries, or domain-specific trust frameworks. +This CIP defines a standardized mechanism to embed KERI ([Key Event Receipt Infrastructure](https://trustoverip.github.io/kswg-keri-specification/)) identifiers within Cardano transaction metadata. KERI provides self-certifying, portable, and decentralized identifiers known as Autonomic Identifiers (AIDs) that can be anchored to various roots of trust—such as verifiable Legal Entity Identifiers (vLEIs), organizational registries, or domain-specific trust frameworks. By including KERI identifiers in transaction metadata, Cardano enables a flexible, trust-agnostic approach to identity binding. This approach supports accountability, legal and regulatory compliance, and interoperability with existing and emerging global identity ecosystems, while remaining compatible with self-sovereign identity principles. @@ -36,7 +36,7 @@ By embedding KERI identifiers into Cardano transaction metadata, this proposal e Below a generic solution is defined to enable metadata signing where a particular ecosystem or use-case may leverage a root of trust of its choosing – each most likely with its own credential chain format. -The credentials used in the KERI ecosystem are known as ACDCs, or [Authentic Chained Data Containers](https://www.rfc-editor.org/rfc/rfc8174). This CIP will not explain at depth how KERI and ACDCs work due to their technical complexity. The [Appendix](#appendix) will however include some expanded explanations to help provide clarity. +The credentials used in the KERI ecosystem are known as ACDCs, or [Authentic Chained Data Containers](https://trustoverip.github.io/kswg-acdc-specification/). This CIP will not explain at depth how KERI and ACDCs work due to their technical complexity. The [Appendix](#appendix) will however include some expanded explanations to help provide clarity. > [!NOTE] > The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119](https://www.rfc-editor.org/rfc/rfc2119) [RFC8174](https://www.rfc-editor.org/rfc/rfc8174) when, and only when, they appear in all capitals, as shown here. @@ -51,7 +51,7 @@ However, as KERI is a maturing technology, wide-spread deployment of watcher net In one way or another, chain indexers must query for Key Event Log updates to validate credential chains and metadata transactions during the process of verification. ### Visualized Identity Lifecycle -The following diagram illustrates the lifecycle of signing authority for a KERI identifier on Cardano. It demonstrates how [attestations](#creation-of-verifiable-records) (`ATTEST`) are invalid before [authority is established](#establishment-of-signing-authority) (`AUTH_BEGIN`), become valid during the authenticated period, and become invalid again after [revocation](#removal-of-signing-authority) (`AUTH_END`). The indexer validates each transaction by checking the current state of the credential chain. +The following diagram illustrates the lifecycle of signing authority for a KERI identifier on Cardano. It demonstrates how [attestations](#creation-of-verifiable-records) (`ATTEST`) are invalid before [authority is established](#establishment-of-signing-authority) (`AUTH_BEGIN`), become valid during the authenticated period, and become invalid again after [revocation](#revoking-of-signing-authority) (`AUTH_END`). The indexer validates each transaction by checking the current state of the credential chain. ```mermaid --- @@ -82,11 +82,11 @@ sequenceDiagram Before attesting to any transactions, the relevant credential chain for the controller must be published on-chain with the following attributes – most of which are used to help simplify indexing: - **t** — A transaction type of `AUTH_BEGIN` is used to establish a signer’s authority using a credential chain. - **i** — The identifier of the signer in the CESR qb64 variant. This MUST match the issuee of the leaf credential in the chain. -- **s** — The schema identifier of the leaf credential in the chain in the CESR qb64 variant. This MUST match the schema of the leaf credential in the chain. Why include? +- **s** — The schema identifier of the leaf credential in the chain in the CESR qb64 variant. This MUST match the schema of the [leaf credential](#identifying-a-credential-chain-type) in the chain. +- **c** — The byte-stream of the credential chain in the CESR qb2 or qb64b variant, for brevity. - **m** — An optional metadata block used to simplify indexing for a particular use-case. For example, the LEI of a legal entity could be contained here. -- **c** — The byte-stream of the credential chain in the CESR qb2 variant, for brevity. -The credential chain should contain all credentials, relevant registry events and attachments. There are various types of ACDC registries, so for simplicity: the credential chain MUST validate with an ACDC 1.0 or 2.0 verifier, assuming that KEL events are already available. +The credential chain should contain all credentials, relevant registry events and attachments. There are various types of ACDC registries, so for simplicity: the credential chain MUST validate with an ACDC v1 or v2 verifier, assuming that KEL events are already available. These attributes can be embedded in the metadata of a transaction using a fixed metadata label. Compact field labels are used for brevity. @@ -114,6 +114,7 @@ To create a persistent signature over data with KERI, signers can anchor a diges - **d** — The digest of the data being signed in the CESR qb64 variant. - **s** — The sequence number of the KERI event, encoded as a hex string. If the KEL of identifier `i` contains an event at sequence number `s` which has a seal value of `{ d: "{{digest}}" }`, it serves as cryptographically verifiable proof that the data was effectively signed by the controller. + A reference to this event in a metadata transaction is structured as follows: ```JSON { @@ -135,8 +136,9 @@ The following attributes are used: - **t** — A transaction type of `AUTH_END` is used to remove a signer’s authority with revocation registry events. - **i** — The identifier of the signer in the CESR qb64 variant. This MUST match the issuee of the leaf credential in the chain. - **s** — The schema identifier of the leaf credential in the chain in the CESR qb64 variant. This MUST match the schema of the leaf credential in the chain. -- **m** — A metadata block used to simplify indexing for a particular use-case. For example, the LEI of a legal entity could be contained here. - **c** — The byte-stream of the revocation registry events in the CESR qb2 variant, for brevity. +- **m** — A metadata block used to simplify indexing for a particular use-case. For example, the LEI of a legal entity could be contained here. + A reference to this event in a metadata transaction is structured as follows: ```JSON { @@ -151,10 +153,10 @@ A reference to this event in a metadata transaction is structured as follows: } ``` -If the successful parsing of the revocation events results in a credential chain that no longer gives authority to the signer, any later ATTEST transactions for this credential chain should be ignored (unless there is another subsequent `AUTH_START`). +If the successful parsing of the revocation events results in a credential chain that no longer gives authority to the signer, any later `ATTEST` transactions for this credential chain should be ignored (unless there is another subsequent `AUTH_START`). -#### Reference Example - vLEI +## Reference Example - vLEI The Global Legal Entity Identifier Foundation (GLEIF) serves as the root of trust for Legal Entity Identifiers (LEIs) worldwide. Their verifiable variant, the vLEI, is based on the KERI and ACDC standards, and are issued by Qualified vLEI Issuers (QVIs). @@ -189,7 +191,7 @@ The above diagram contains 3 credentials which are cryptographically chained: The schema for the signer credential may be found here. It contains an attribute `labels` which is an array of metadata label numbers for which the signer has the authority to create verifiable records over. -##### Establishment of signing authority +### Establishment of signing authority For this example, a signer controlling the identifier `EKtQ1lymrnrh3qv5S18PBzQ7ukHGFJ7EXkH7B22XEMIL` is holding a metadata signer credential valid for label `1447`. The following is the expected transaction format to publish the credential chain: @@ -224,7 +226,7 @@ After verifying the validity of the credential chain with an ACDC verifier, ther 3. The LEI attribute of the Legal Entity vLEI credential is `50670047U83746F70E20`. 4. The Qualified vLEI Issuer credential is issued by GLEIF’s External identifier, as listed [here](https://gleif-it.github.io/.well-known/). -##### Creation of verifiable records +### Creation of verifiable records The following is an attestation transaction for metadata label `1447`. ```JSON { From d83834c8176da25a7ae23a4eba5fd5609279a4a5 Mon Sep 17 00:00:00 2001 From: Kammerlo Date: Mon, 10 Nov 2025 09:44:48 +0100 Subject: [PATCH 23/31] docs: incorporated feedback --- CIP-????/README.md | 56 ++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 52 insertions(+), 4 deletions(-) diff --git a/CIP-????/README.md b/CIP-????/README.md index 49d749c730..4a667d19d9 100644 --- a/CIP-????/README.md +++ b/CIP-????/README.md @@ -51,7 +51,7 @@ However, as KERI is a maturing technology, wide-spread deployment of watcher net In one way or another, chain indexers must query for Key Event Log updates to validate credential chains and metadata transactions during the process of verification. ### Visualized Identity Lifecycle -The following diagram illustrates the lifecycle of signing authority for a KERI identifier on Cardano. It demonstrates how [attestations](#creation-of-verifiable-records) (`ATTEST`) are invalid before [authority is established](#establishment-of-signing-authority) (`AUTH_BEGIN`), become valid during the authenticated period, and become invalid again after [revocation](#revoking-of-signing-authority) (`AUTH_END`). The indexer validates each transaction by checking the current state of the credential chain. +The following diagram illustrates the lifecycle of signing authority for a KERI identifier on Cardano. It demonstrates how [attestations](#creation-of-verifiable-records) (`ATTEST`) are invalid before [authority is established](#establishment-of-signing-authority) (`AUTH_BEGIN`), become valid during the authenticated period, and become invalid again after [revocation](#revoking-of-signing-authority) (`AUTH_END`). ```mermaid --- @@ -79,7 +79,7 @@ sequenceDiagram Note right of Indexer: ❌ No valid credential ``` ### Establishment of signing authority -Before attesting to any transactions, the relevant credential chain for the controller must be published on-chain with the following attributes – most of which are used to help simplify indexing: +Before attesting to any transactions, the relevant [credential chain](#credential-chains) for the controller must be published on-chain with the following attributes – most of which are used to help simplify indexing: - **t** — A transaction type of `AUTH_BEGIN` is used to establish a signer’s authority using a credential chain. - **i** — The identifier of the signer in the CESR qb64 variant. This MUST match the issuee of the leaf credential in the chain. - **s** — The schema identifier of the leaf credential in the chain in the CESR qb64 variant. This MUST match the schema of the [leaf credential](#identifying-a-credential-chain-type) in the chain. @@ -137,7 +137,7 @@ The following attributes are used: - **i** — The identifier of the signer in the CESR qb64 variant. This MUST match the issuee of the leaf credential in the chain. - **s** — The schema identifier of the leaf credential in the chain in the CESR qb64 variant. This MUST match the schema of the leaf credential in the chain. - **c** — The byte-stream of the revocation registry events in the CESR qb2 variant, for brevity. -- **m** — A metadata block used to simplify indexing for a particular use-case. For example, the LEI of a legal entity could be contained here. +- **m** — An optional metadata block used to simplify indexing for a particular use-case. For example, the LEI of a legal entity could be contained here. A reference to this event in a metadata transaction is structured as follows: ```JSON @@ -221,7 +221,7 @@ The credential chain `c` should be a qb2 CESR stream containing: A test example may be found here in qb64 format - this should be converted to qb2 before being pushed on-chain. After verifying the validity of the credential chain with an ACDC verifier, there are a number of extra validation steps to complete as business logic: -1. `EKtQ1lymrnrh3qv5S18PBzQ7ukHGFJ7EXkH7B22XEMIL` is the issuee of the metadata signer credential. +1. `EKtQ1lymrnrh3qv5S18PBzQ7ukHGFJ7EXkH7B22XEMIL` is the issuee of the metadata signer credential with a schema ID of `ED_GbUPpS8ZJEY-u8OB3QVe9C_CAFBdSimS5KxclkgWT`. 2. The label attribute of the credential is `[1447]`. 3. The LEI attribute of the Legal Entity vLEI credential is `50670047U83746F70E20`. 4. The Qualified vLEI Issuer credential is issued by GLEIF’s External identifier, as listed [here](https://gleif-it.github.io/.well-known/). @@ -245,6 +245,54 @@ Validation steps: 2. The CESR digest of the data at label 1447 is `ELC5L3iBVD77d_MYbYGGCUQgqQBju1o4x1Ud-z2sL-ux`. 3. The event in the controller’s KEL at sequence number `1a` (26th event) is `{ d: “ELC5L3iBVD77d_MYbYGGCUQgqQBju1o4x1Ud-z2sL-ux” }`. +### Revoking signing authority + +When a credential must be revoked (for example, due to employee termination, credential compromise, or policy changes) the legal entity publishes an `AUTH_END` transaction containing the revocation registry events. + +The following is an example revocation transaction: +```JSON +{ + "????": + { + "t": "AUTH_END", + "s": "ED_GbUPpS8ZJEY-u8OB3QVe9C_CAFBdSimS5KxclkgWT", + "i": "EKtQ1lymrnrh3qv5S18PBzQ7ukHGFJ7EXkH7B22XEMIL", + "c": "{{revocationRegistryEventsByteStream}}", + "m": + { + "l": [1447], + "LEI": "50670047U83746F70E20" + } + } +} +``` + +The revocation registry events in `c` should contain the necessary ACDC registry events that mark the credential as revoked. Once processed by the indexer, the following validation logic applies: + +1. The indexer parses the revocation events and validates them against the credential chain. +2. If the revocation is valid, the identifier `EKtQ1lymrnrh3qv5S18PBzQ7ukHGFJ7EXkH7B22XEMIL` loses signing authority for label `1447` from this transaction forward. +3. Any subsequent `ATTEST` transactions using this identifier will be ignored and treated as unverified. + +For example, if the following transaction appears after revocation: +```JSON +{ + "XXXX": { + "t": "ATTEST", + "i": "EKtQ1lymrnrh3qv5S18PBzQ7ukHGFJ7EXkH7B22XEMIL", + "d": "ELC5L3iBVD77d_MYbYGGCUQgqQBju1o4x1Ud-z2sL-ux", + "s": "1b" + }, + "1447": "{{someApplicationMetadata}}" +} +``` + +The indexer will reject this attestation because: +1. The credential chain for `EKtQ1lymrnrh3qv5S18PBzQ7ukHGFJ7EXkH7B22XEMIL` has been revoked. +2. No valid signing authority exists for this identifier on label `1447`. +3. The transaction is marked as **unverified** and should not be trusted by any application relying on the indexer. + +Only if a new `AUTH_BEGIN` transaction is published with a fresh, valid credential chain would the identifier regain signing authority. + ## Appendix ### Credential chains From c7e8a7029a65deca3019224b7825e3ec62882576 Mon Sep 17 00:00:00 2001 From: Kammerlo Date: Mon, 10 Nov 2025 11:28:24 +0100 Subject: [PATCH 24/31] docs: added rationale --- CIP-????/README.md | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/CIP-????/README.md b/CIP-????/README.md index 4a667d19d9..9b89cf9338 100644 --- a/CIP-????/README.md +++ b/CIP-????/README.md @@ -293,6 +293,44 @@ The indexer will reject this attestation because: Only if a new `AUTH_BEGIN` transaction is published with a fresh, valid credential chain would the identifier regain signing authority. + +## Rationale: how does this CIP achieve its goals? + +This CIP enables entities (including legal entities, organizations, DAOs, and individuals) to cryptographically prove their identity on Cardano by linking verifiable credential chains (such as vLEIs) to on-chain transactions. This connection establishes accountability and transparency, enabling blockchain adoption in highly regulated environments where transactions must be traceable to recognized entities, while also supporting flexible identity frameworks for various use cases beyond traditional corporate structures. + +### Achieving Accountability Through Verifiable Identity + +The core goal of establishing accountability is achieved through several key mechanisms: + +**Persistent Identity Binding**: By anchoring KERI identifiers in transaction metadata, this CIP creates an immutable, publicly auditable link between a transaction and a specific entity. Unlike traditional blockchain addresses which are pseudonymous, KERI identifiers can be verified against credential chains that ultimately connect to legally recognized entities (e.g., through LEIs issued by GLEIF). This transforms anonymous blockchain activity into accountable actions. + +**Temporal Authority Control**: The `AUTH_BEGIN` and `AUTH_END` lifecycle allows precise control over when an identifier has signing authority. This supports real-world scenarios like employee onboarding/offboarding or credential expiration, ensuring that only authorized representatives can act on behalf of an entity at any given time. Indexers can deterministically verify whether any attestation was made during a valid authority period. + +**Multi-Layer Verification**: The credential chain structure enables verification at multiple levels—from cryptographic signature validity, to credential issuance by authorized issuers, to the root of trust (e.g., GLEIF). This layered approach means that breaking accountability would require compromising multiple independent systems, not just a single private key. + +### Design Trade-offs + +The metadata-based approach was chosen for its simplicity and flexibility: + +**Advantages:** +- Straightforward implementation for wallets and transaction builders +- Flexible credential schemas without protocol changes +- Full backward compatibility with existing infrastructure + +**Limitations:** +- Validation must occur off-chain through indexers (smart contracts cannot enforce credential checks) - This limitation can be solved by writing another CIP or extending this +- Requires additional infrastructure (indexers, KERI watcher networks) + +The metadata is immutably recorded on-chain, and anyone can independently verify the cryptographic proofs by validating the credential chains against published Key Event Logs. + +### Cryptographic Trust + +Unlike oracle networks that rely on consensus among multiple nodes, KERI-based verification relies purely on cryptographic signatures and tamper-evident event logs. Verifiers can independently validate credentials without trusting any third party—the only trust assumption is in the root of trust (e.g., GLEIF for vLEIs), which is already established in real-world legal frameworks. + +By adopting KERI, an existing standard from the Trust over IP Foundation, this CIP ensures interoperability across ecosystems, credential portability, and alignment with emerging regulatory requirements for digital identity. This standards-based approach means that implementations can leverage existing tooling, benefit from ongoing security research, and maintain compatibility as the KERI ecosystem evolves. + +## Path to Active + ## Appendix ### Credential chains From ac4057aec21a74d168616f81e1feedb812c8fa5a Mon Sep 17 00:00:00 2001 From: Kammerlo Date: Mon, 10 Nov 2025 14:37:24 +0100 Subject: [PATCH 25/31] docs: added example data --- CIP-????/README.md | 6 +- CIP-????/example-credential-chain.json | 133 ++++++++++++++++++ CIP-????/example-revocation-event.json | 10 ++ ...ei-cardano-metadata-signer-credential.json | 126 +++++++++++++++++ 4 files changed, 272 insertions(+), 3 deletions(-) create mode 100644 CIP-????/example-credential-chain.json create mode 100644 CIP-????/example-revocation-event.json create mode 100644 CIP-????/vlei-cardano-metadata-signer-credential.json diff --git a/CIP-????/README.md b/CIP-????/README.md index 9b89cf9338..ccf3f779e0 100644 --- a/CIP-????/README.md +++ b/CIP-????/README.md @@ -200,7 +200,7 @@ The following is the expected transaction format to publish the credential chain "????": { "t": "AUTH_BEGIN", - "s": "ED_GbUPpS8ZJEY-u8OB3QVe9C_CAFBdSimS5KxclkgWT", + "s": "EJVgEQO8BEhGGM7GcAjlqoKG1upeuBZj9WjvjZo353sQ", "i": "EKtQ1lymrnrh3qv5S18PBzQ7ukHGFJ7EXkH7B22XEMIL", "c": "{{credentialChainByteStream}}", "m": @@ -218,10 +218,10 @@ The credential chain `c` should be a qb2 CESR stream containing: - Registry events for each revocation registry (`vcp`) - All necessary CESR attachments -A test example may be found here in qb64 format - this should be converted to qb2 before being pushed on-chain. +A test example may be found [here](example-credential-chain.json) in qb64 format - this should be converted to qb2 before being pushed on-chain. After verifying the validity of the credential chain with an ACDC verifier, there are a number of extra validation steps to complete as business logic: -1. `EKtQ1lymrnrh3qv5S18PBzQ7ukHGFJ7EXkH7B22XEMIL` is the issuee of the metadata signer credential with a schema ID of `ED_GbUPpS8ZJEY-u8OB3QVe9C_CAFBdSimS5KxclkgWT`. +1. `EKtQ1lymrnrh3qv5S18PBzQ7ukHGFJ7EXkH7B22XEMIL` is the issuee of the metadata signer credential with a schema ID of `EJVgEQO8BEhGGM7GcAjlqoKG1upeuBZj9WjvjZo353sQ`. 2. The label attribute of the credential is `[1447]`. 3. The LEI attribute of the Legal Entity vLEI credential is `50670047U83746F70E20`. 4. The Qualified vLEI Issuer credential is issued by GLEIF’s External identifier, as listed [here](https://gleif-it.github.io/.well-known/). diff --git a/CIP-????/example-credential-chain.json b/CIP-????/example-credential-chain.json new file mode 100644 index 0000000000..3ee78ecafb --- /dev/null +++ b/CIP-????/example-credential-chain.json @@ -0,0 +1,133 @@ +{ + "v": "KERI10JSON000113_", + "t": "vcp", + "d": "EFfQPwW9s8HQV-zq2NTGks_WYT79Z046mhIJwPQxlfn0", + "i": "EFfQPwW9s8HQV-zq2NTGks_WYT79Z046mhIJwPQxlfn0", + "ii": "EOosFLj1gOfRFEx5g5TSCPdpml9jM9_jIaWI5pZO5YCU", + "s": "0", + "c": [ + "NB" + ], + "bt": "0", + "b": [], + "n": "AFltXlPUmiWy8_v8d9f6jj1E2l7LX1UWjU7hGtrp-1xW" +}-VAS-GAB0AAAAAAAAAAAAAAAAAAAAAABEKiuK7uqunvbRxirmi9gqfuOGfQSZuqCT9b0WEVFx_Cf +{ + "v": "KERI10JSON000113_", + "t": "vcp", + "d": "EOzV2Oj64Wwe9QetkB_FCmIvoTI_6OKn7nB4W51wJQ-a", + "i": "EOzV2Oj64Wwe9QetkB_FCmIvoTI_6OKn7nB4W51wJQ-a", + "ii": "EARtegK3M61uNJ5wyuznNjngYP0kJm1-KHv5fh-8UFWS", + "s": "0", + "c": [ + "NB" + ], + "bt": "0", + "b": [], + "n": "AM0aXrE5B79nt1_FOffK7N_rMw1VkYLRe1KB60rwRplM" +}-VAS-GAB0AAAAAAAAAAAAAAAAAAAAAABEPQN2EE4bNWu6-1vXoLMfTUumlHFEAr9-p4_CeoxfchP +{ + "v": "KERI10JSON000113_", + "t": "vcp", + "d": "EOWTJBCuCpDtamFQrepwyC2WwbsOzWIP0fhRnT8eZeLC", + "i": "EOWTJBCuCpDtamFQrepwyC2WwbsOzWIP0fhRnT8eZeLC", + "ii": "EF--c3_VLg-aaoI-y9kKc0XSQD2-bZoiyk0U7Vym9p-l", + "s": "0", + "c": [ + "NB" + ], + "bt": "0", + "b": [], + "n": "AG_SUFGr-Nvk_t1Z7QUAjwsjoFw9GF4tZEt8IcNwrjFe" +}-VAS-GAB0AAAAAAAAAAAAAAAAAAAAAABEFVhm8TjehsDvAJGxlI5ufy_Mxd5j-B1KSqB-YLC1JWV +{ + "v": "KERI10JSON0000ed_", + "t": "iss", + "d": "EOkDhM2BZL2dXuWydnDvIl7kWj5q2bVZXnPNLtr1Wtop", + "i": "EIUaX_JLblNtJQQg0gh7Ka4h64gbwOhqlPl9QC-7M6DZ", + "s": "0", + "ri": "EFfQPwW9s8HQV-zq2NTGks_WYT79Z046mhIJwPQxlfn0", + "dt": "2025-11-10T11:43:47.242000+00:00" +}-VAS-GAB0AAAAAAAAAAAAAAAAAAAAAACEDFK7pUh-Ez7kk0knpLl1m8iA59_BE4_Rkv8QtHMbRuE +{ + "v": "KERI10JSON0000ed_", + "t": "iss", + "d": "ELlER5cq0f8sPsZKjz_jcdegz65uErDiCqfbYlYQHlim", + "i": "EBK-BG-8-ZhvQ7ml52PWOVJn30IUviSeC7VepeU_mZXK", + "s": "0", + "ri": "EOzV2Oj64Wwe9QetkB_FCmIvoTI_6OKn7nB4W51wJQ-a", + "dt": "2025-11-10T11:43:51.081000+00:00" +}-VAS-GAB0AAAAAAAAAAAAAAAAAAAAAACEIXsXeDBh9kSbE4pvn3uCPzKxE9Pkg4t-JuRKyLGrUI9 +{ + "v": "KERI10JSON0000ed_", + "t": "iss", + "d": "EOyo58VXZv4qVVs8jczoTmFlwffJDC8yirqpqecFW3jj", + "i": "EPSkZ1-E6ojESV9mt20vA0YUfoYAD8dxYyn4-ochHMtV", + "s": "0", + "ri": "EOWTJBCuCpDtamFQrepwyC2WwbsOzWIP0fhRnT8eZeLC", + "dt": "2025-11-10T11:43:58.630000+00:00" +}-VAS-GAB0AAAAAAAAAAAAAAAAAAAAAACEFuQPJfiOsO71geAaItT4DGH7xr0ZtaDs8ycsnpxki6k +{ + "v": "ACDC10JSON000197_", + "d": "EIUaX_JLblNtJQQg0gh7Ka4h64gbwOhqlPl9QC-7M6DZ", + "i": "EOosFLj1gOfRFEx5g5TSCPdpml9jM9_jIaWI5pZO5YCU", + "ri": "EFfQPwW9s8HQV-zq2NTGks_WYT79Z046mhIJwPQxlfn0", + "s": "EBfdlu8R27Fbx-ehrqwImnK-8Cm79sqbAQ4MmvEAYqao", + "a": { + "d": "EC9iDB-5CIrhu_R68eXQ9HgDT_vxTqSPZXU-TPVzr6-F", + "i": "EARtegK3M61uNJ5wyuznNjngYP0kJm1-KHv5fh-8UFWS", + "dt": "2025-11-10T11:43:47.242000+00:00", + "LEI": "50670047U83746F70E20" + } +}-IABEIUaX_JLblNtJQQg0gh7Ka4h64gbwOhqlPl9QC-7M6DZ0AAAAAAAAAAAAAAAAAAAAAAAEOkDhM2BZL2dXuWydnDvIl7kWj5q2bVZXnPNLtr1Wtop +{ + "v": "ACDC10JSON0005c8_", + "d": "EBK-BG-8-ZhvQ7ml52PWOVJn30IUviSeC7VepeU_mZXK", + "i": "EARtegK3M61uNJ5wyuznNjngYP0kJm1-KHv5fh-8UFWS", + "ri": "EOzV2Oj64Wwe9QetkB_FCmIvoTI_6OKn7nB4W51wJQ-a", + "s": "ENPXp1vQzRF6JwIuS-mp2U8Uf1MoADoP_GqQ62VsDZWY", + "a": { + "d": "EB9PCr5APfA1o9LRkO45kijrvoQuH1N5Te4U5JhjpzOO", + "i": "EF--c3_VLg-aaoI-y9kKc0XSQD2-bZoiyk0U7Vym9p-l", + "dt": "2025-11-10T11:43:51.081000+00:00", + "LEI": "50670047U83746F70E20" + }, + "e": { + "d": "EC4U5Yxjv1TbJm6fVwi9b_mPr1kpqyv0EQM9Gb0AKDz8", + "qvi": { + "n": "EIUaX_JLblNtJQQg0gh7Ka4h64gbwOhqlPl9QC-7M6DZ", + "s": "EBfdlu8R27Fbx-ehrqwImnK-8Cm79sqbAQ4MmvEAYqao" + } + }, + "r": { + "d": "EGZ97EjPSINR-O-KHDN_uw4fdrTxeuRXrqT5ZHHQJujQ", + "usageDisclaimer": { + "l": "Usage of a valid, unexpired, and non-revoked vLEI Credential, as defined in the associated Ecosystem Governance Framework, does not assert that the Legal Entity is trustworthy, honest, reputable in its business dealings, safe to do business with, or compliant with any laws or that an implied or expressly intended purpose will be fulfilled." + }, + "issuanceDisclaimer": { + "l": "All information in a valid, unexpired, and non-revoked vLEI Credential, as defined in the associated Ecosystem Governance Framework, is accurate as of the date the validation process was complete. The vLEI Credential has been issued to the legal entity or person named in the vLEI Credential as the subject; and the qualified vLEI Issuer exercised reasonable care to perform the validation process set forth in the vLEI Ecosystem Governance Framework." + } + } +}-IABEBK-BG-8-ZhvQ7ml52PWOVJn30IUviSeC7VepeU_mZXK0AAAAAAAAAAAAAAAAAAAAAAAELlER5cq0f8sPsZKjz_jcdegz65uErDiCqfbYlYQHlim +{ + "v": "ACDC10JSON000230_", + "d": "EPSkZ1-E6ojESV9mt20vA0YUfoYAD8dxYyn4-ochHMtV", + "i": "EF--c3_VLg-aaoI-y9kKc0XSQD2-bZoiyk0U7Vym9p-l", + "ri": "EOWTJBCuCpDtamFQrepwyC2WwbsOzWIP0fhRnT8eZeLC", + "s": "EJVgEQO8BEhGGM7GcAjlqoKG1upeuBZj9WjvjZo353sQ", + "a": { + "d": "EKGU79bIkzxFsr-ZcoOLyZyX5mD4ScRbylGNNVbeiOW3", + "i": "EKtQ1lymrnrh3qv5S18PBzQ7ukHGFJ7EXkH7B22XEMIL", + "dt": "2025-11-10T11:43:58.630000+00:00", + "labels": [ + 1447 + ] + }, + "e": { + "d": "EPvTf6H9kJBJ87jDXR-IM-jSwWoGwQ_AhuwnIpq0lhqG", + "le": { + "n": "EBK-BG-8-ZhvQ7ml52PWOVJn30IUviSeC7VepeU_mZXK", + "s": "ENPXp1vQzRF6JwIuS-mp2U8Uf1MoADoP_GqQ62VsDZWY" + } + } +}-IABEPSkZ1-E6ojESV9mt20vA0YUfoYAD8dxYyn4-ochHMtV0AAAAAAAAAAAAAAAAAAAAAAAEOyo58VXZv4qVVs8jczoTmFlwffJDC8yirqpqecFW3jj \ No newline at end of file diff --git a/CIP-????/example-revocation-event.json b/CIP-????/example-revocation-event.json new file mode 100644 index 0000000000..e9fe242c10 --- /dev/null +++ b/CIP-????/example-revocation-event.json @@ -0,0 +1,10 @@ +{ + "v": "KERI10JSON000120_", + "t": "rev", + "d": "EIYQA02v1cjNrPn1KhIZXof56LRLmCNPWnaeSyZ87KeU", + "i": "EPSkZ1-E6ojESV9mt20vA0YUfoYAD8dxYyn4-ochHMtV", + "s": "1", + "ri": "EOWTJBCuCpDtamFQrepwyC2WwbsOzWIP0fhRnT8eZeLC", + "p": "EOyo58VXZv4qVVs8jczoTmFlwffJDC8yirqpqecFW3jj", + "dt": "2025-11-10T13:00:40.243000+00:00" +}-VAS-GAB0AAAAAAAAAAAAAAAAAAAAAADEDNyGD0Vt0UgfX3NZuf3JhHY34kTzxGZfhApeISBCBUI \ No newline at end of file diff --git a/CIP-????/vlei-cardano-metadata-signer-credential.json b/CIP-????/vlei-cardano-metadata-signer-credential.json new file mode 100644 index 0000000000..6608e1dcc5 --- /dev/null +++ b/CIP-????/vlei-cardano-metadata-signer-credential.json @@ -0,0 +1,126 @@ +{ + "$id": "EJVgEQO8BEhGGM7GcAjlqoKG1upeuBZj9WjvjZo353sQ", + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "vLEI Cardano Metadata Signer Credential", + "description": "A vLEI Cardano Metadata Signer Credential issued to a person or machine which may sign metadata embedded in Cardano transactions on behalf of a Legal Entity", + "type": "object", + "credentialType": "vLEICardanoMetadataSignerCredential", + "version": "1.0.0", + "properties": { + "v": { + "description": "Version", + "type": "string" + }, + "d": { + "description": "Credential SAID", + "type": "string" + }, + "i": { + "description": "Issuer AID", + "type": "string" + }, + "ri": { + "description": "Credential status registry", + "type": "string" + }, + "s": { + "description": "Schema SAID", + "type": "string" + }, + "a": { + "oneOf": [ + { + "description": "Attributes block SAID", + "type": "string" + }, + { + "$id": "EBCRiKplQ_uucawOH7lVt0PErQs_9Y2coohaC12zy8f3", + "description": "Attributes block", + "type": "object", + "properties": { + "d": { + "description": "Attributes block SAID", + "type": "string" + }, + "i": { + "description": "Issuee AID", + "type": "string" + }, + "dt": { + "description": "Issuance date time", + "type": "string", + "format": "date-time" + }, + "labels": { + "description": "Array of metadata labels that can be signed", + "type": "array", + "items": { + "type": "number" + } + } + }, + "additionalProperties": false, + "required": [ + "i", + "dt", + "labels" + ] + } + ] + }, + "e": { + "oneOf": [ + { + "description": "Edges block SAID", + "type": "string" + }, + { + "$id": "EHeZGaLBhCc_-sAcyAEgFFeCkxgnqCubPOBuEvoh9jHX", + "description": "Edges block for issuance from Legal Entity", + "type": "object", + "properties": { + "d": { + "description": "SAID of edges block", + "type": "string" + }, + "le": { + "description": "Chain to legal entity vLEI credential", + "type": "object", + "properties": { + "n": { + "description": "SAID of the ACDC to which the edge connects", + "type": "string" + }, + "s": { + "description": "SAID of required schema of the credential pointed to by this node", + "type": "string", + "const": "ENPXp1vQzRF6JwIuS-mp2U8Uf1MoADoP_GqQ62VsDZWY" + } + }, + "additionalProperties": false, + "required": [ + "n", + "s" + ] + } + }, + "additionalProperties": false, + "required": [ + "d", + "le" + ] + } + ] + } + }, + "additionalProperties": false, + "required": [ + "v", + "i", + "ri", + "s", + "d", + "a", + "e" + ] +} \ No newline at end of file From 2f2948e07240c1ead209ddfd779a372c640e97be Mon Sep 17 00:00:00 2001 From: Kammerlo Date: Mon, 10 Nov 2025 14:42:30 +0100 Subject: [PATCH 26/31] docs: replaced old schema --- CIP-????/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CIP-????/README.md b/CIP-????/README.md index ccf3f779e0..2389835307 100644 --- a/CIP-????/README.md +++ b/CIP-????/README.md @@ -255,7 +255,7 @@ The following is an example revocation transaction: "????": { "t": "AUTH_END", - "s": "ED_GbUPpS8ZJEY-u8OB3QVe9C_CAFBdSimS5KxclkgWT", + "s": "EJVgEQO8BEhGGM7GcAjlqoKG1upeuBZj9WjvjZo353sQ", "i": "EKtQ1lymrnrh3qv5S18PBzQ7ukHGFJ7EXkH7B22XEMIL", "c": "{{revocationRegistryEventsByteStream}}", "m": From 9b2525ac6f8fcbdd6eb0f5a746ef4ccf4868a1d9 Mon Sep 17 00:00:00 2001 From: Kammerlo Date: Mon, 10 Nov 2025 14:46:15 +0100 Subject: [PATCH 27/31] docs: renamed files to cesr and linked revocation in doc --- CIP-????/README.md | 5 ++--- ...e-credential-chain.json => example-credential-chain.cesr} | 0 ...e-revocation-event.json => example-revocation-event.cesr} | 0 3 files changed, 2 insertions(+), 3 deletions(-) rename CIP-????/{example-credential-chain.json => example-credential-chain.cesr} (100%) rename CIP-????/{example-revocation-event.json => example-revocation-event.cesr} (100%) diff --git a/CIP-????/README.md b/CIP-????/README.md index 2389835307..b96ceedde6 100644 --- a/CIP-????/README.md +++ b/CIP-????/README.md @@ -218,7 +218,7 @@ The credential chain `c` should be a qb2 CESR stream containing: - Registry events for each revocation registry (`vcp`) - All necessary CESR attachments -A test example may be found [here](example-credential-chain.json) in qb64 format - this should be converted to qb2 before being pushed on-chain. +A test example may be found [here](example-credential-chain.cesr) in qb64 format - this should be converted to qb2 before being pushed on-chain. After verifying the validity of the credential chain with an ACDC verifier, there are a number of extra validation steps to complete as business logic: 1. `EKtQ1lymrnrh3qv5S18PBzQ7ukHGFJ7EXkH7B22XEMIL` is the issuee of the metadata signer credential with a schema ID of `EJVgEQO8BEhGGM7GcAjlqoKG1upeuBZj9WjvjZo353sQ`. @@ -247,8 +247,7 @@ Validation steps: ### Revoking signing authority -When a credential must be revoked (for example, due to employee termination, credential compromise, or policy changes) the legal entity publishes an `AUTH_END` transaction containing the revocation registry events. - +When a credential must be revoked (for example, due to employee termination, credential compromise, or policy changes) the legal entity publishes an `AUTH_END` transaction containing the revocation registry events. An example of how a revoking event can be found [here](example-revocation-event.cesr) The following is an example revocation transaction: ```JSON { diff --git a/CIP-????/example-credential-chain.json b/CIP-????/example-credential-chain.cesr similarity index 100% rename from CIP-????/example-credential-chain.json rename to CIP-????/example-credential-chain.cesr diff --git a/CIP-????/example-revocation-event.json b/CIP-????/example-revocation-event.cesr similarity index 100% rename from CIP-????/example-revocation-event.json rename to CIP-????/example-revocation-event.cesr From 8621abc7d6de4f7783e1d64aed18ae77d428be8b Mon Sep 17 00:00:00 2001 From: Kammerlo Date: Mon, 10 Nov 2025 15:54:50 +0100 Subject: [PATCH 28/31] docs: incorporated feedback --- CIP-0010/registry.json | 2 +- CIP-????/README.md | 50 ++++++++++++++++++++++++++++++++++-------- 2 files changed, 42 insertions(+), 10 deletions(-) diff --git a/CIP-0010/registry.json b/CIP-0010/registry.json index 675f0da41c..8340fbb49e 100644 --- a/CIP-0010/registry.json +++ b/CIP-0010/registry.json @@ -157,6 +157,6 @@ }, { "transaction_metadatum_label": "????", - "description": "CIP-???? - Keri Decentralized Identifiers" + "description": "CIP-???? - KERI-backed metadata attestations" } ] diff --git a/CIP-????/README.md b/CIP-????/README.md index b96ceedde6..4c5d929454 100644 --- a/CIP-????/README.md +++ b/CIP-????/README.md @@ -1,6 +1,6 @@ --- CIP: ???? -Title: Keri Decentralized Identifiers +Title: KERI-backed metadata attestations Category: Metadata Status: Proposed Authors: @@ -84,6 +84,7 @@ Before attesting to any transactions, the relevant [credential chain](#credentia - **i** — The identifier of the signer in the CESR qb64 variant. This MUST match the issuee of the leaf credential in the chain. - **s** — The schema identifier of the leaf credential in the chain in the CESR qb64 variant. This MUST match the schema of the [leaf credential](#identifying-a-credential-chain-type) in the chain. - **c** — The byte-stream of the credential chain in the CESR qb2 or qb64b variant, for brevity. +- **v** - Version of the CIP and minimum version of KERI and ACDC to ensure compatibility. - **m** — An optional metadata block used to simplify indexing for a particular use-case. For example, the LEI of a legal entity could be contained here. The credential chain should contain all credentials, relevant registry events and attachments. There are various types of ACDC registries, so for simplicity: the credential chain MUST validate with an ACDC v1 or v2 verifier, assuming that KEL events are already available. @@ -99,6 +100,11 @@ The metadata is structured as follows: "s": "{{saidOfLeafCredentialSchema}}", "i": "{{aidOfSigner}}", "c": "{{byteStream}}", + "v": { + "v": "{{CIP Version String}}", + "k": "{{KERI Version String}}", + "a": "{{ACDC Version String}}" + }, "m": "{{optionalMetadataBlock}}" } } @@ -113,6 +119,7 @@ To create a persistent signature over data with KERI, signers can anchor a diges - **i** — The identifier of the signer in the CESR qb64 variant. - **d** — The digest of the data being signed in the CESR qb64 variant. - **s** — The sequence number of the KERI event, encoded as a hex string. +- **v** - Version of the CIP. KERI and ACDC version isn't needed here. If the KEL of identifier `i` contains an event at sequence number `s` which has a seal value of `{ d: "{{digest}}" }`, it serves as cryptographically verifiable proof that the data was effectively signed by the controller. A reference to this event in a metadata transaction is structured as follows: @@ -122,7 +129,10 @@ A reference to this event in a metadata transaction is structured as follows: "t": "ATTEST", "i": "{{aidOfSigner}}", "d": "{{digest}}", - "s": "{{hexEncodedSequenceNumber}}" + "s": "{{hexEncodedSequenceNumber}}", + "v": { + "v": "{{CIP Version String}}" + }, }, "YYYY": "{{someApplicationMetadata}}" } @@ -136,7 +146,8 @@ The following attributes are used: - **t** — A transaction type of `AUTH_END` is used to remove a signer’s authority with revocation registry events. - **i** — The identifier of the signer in the CESR qb64 variant. This MUST match the issuee of the leaf credential in the chain. - **s** — The schema identifier of the leaf credential in the chain in the CESR qb64 variant. This MUST match the schema of the leaf credential in the chain. -- **c** — The byte-stream of the revocation registry events in the CESR qb2 variant, for brevity. +- **c** — The byte-stream of the revocation registry events in the CESR qb2 or qb64b variant, for brevity. +- **v** - Version of the CIP and minimum version of KERI and ACDC to ensure compatibility. - **m** — An optional metadata block used to simplify indexing for a particular use-case. For example, the LEI of a legal entity could be contained here. A reference to this event in a metadata transaction is structured as follows: @@ -147,7 +158,12 @@ A reference to this event in a metadata transaction is structured as follows: "t": "AUTH_END", "s": "{{saidOfLeafCredentialSchema}}", "i": "{{aidOfSigner}}", - "c": "{{byteStream}}", + "c": "{{byteStream}}",, + "v": { + "v": "{{CIP Version String}}", + "k": "{{KERI Version String}}", + "a": "{{ACDC Version String}}" + }, "m": "{{optionalMetadataBlock}}" } } @@ -203,6 +219,11 @@ The following is the expected transaction format to publish the credential chain "s": "EJVgEQO8BEhGGM7GcAjlqoKG1upeuBZj9WjvjZo353sQ", "i": "EKtQ1lymrnrh3qv5S18PBzQ7ukHGFJ7EXkH7B22XEMIL", "c": "{{credentialChainByteStream}}", + "v": { + "v": "1.0", + "k": "KERI10", + "a": "KERI10" + }, "m": { "l": [1447], @@ -234,7 +255,10 @@ The following is an attestation transaction for metadata label `1447`. "t": "ATTEST", "i": "EKtQ1lymrnrh3qv5S18PBzQ7ukHGFJ7EXkH7B22XEMIL", "d": "ELC5L3iBVD77d_MYbYGGCUQgqQBju1o4x1Ud-z2sL-ux", - "s": "1a" + "s": "1a", + "v": { + "v": "1.0" + } }, "1447": "{{someApplicationMetadata}}" } @@ -247,7 +271,7 @@ Validation steps: ### Revoking signing authority -When a credential must be revoked (for example, due to employee termination, credential compromise, or policy changes) the legal entity publishes an `AUTH_END` transaction containing the revocation registry events. An example of how a revoking event can be found [here](example-revocation-event.cesr) +When a credential must be revoked (for example, due to employee termination, credential compromise, or policy changes) the legal entity publishes an `AUTH_END` transaction containing the revocation registry events. A sample revocation event stream can be found [here](example-revocation-event.cesr). The following is an example revocation transaction: ```JSON { @@ -257,6 +281,11 @@ The following is an example revocation transaction: "s": "EJVgEQO8BEhGGM7GcAjlqoKG1upeuBZj9WjvjZo353sQ", "i": "EKtQ1lymrnrh3qv5S18PBzQ7ukHGFJ7EXkH7B22XEMIL", "c": "{{revocationRegistryEventsByteStream}}", + "v": { + "v": "1.0", + "k": "KERI10", + "a": "ACDC10" + }, "m": { "l": [1447], @@ -269,8 +298,8 @@ The following is an example revocation transaction: The revocation registry events in `c` should contain the necessary ACDC registry events that mark the credential as revoked. Once processed by the indexer, the following validation logic applies: 1. The indexer parses the revocation events and validates them against the credential chain. -2. If the revocation is valid, the identifier `EKtQ1lymrnrh3qv5S18PBzQ7ukHGFJ7EXkH7B22XEMIL` loses signing authority for label `1447` from this transaction forward. -3. Any subsequent `ATTEST` transactions using this identifier will be ignored and treated as unverified. + +If the revocation is valid, the identifier `EKtQ1lymrnrh3qv5S18PBzQ7ukHGFJ7EXkH7B22XEMIL` loses signing authority for label `1447` from this transaction forward. Any subsequent `ATTEST` transactions using this identifier will be ignored and treated as unverified. For example, if the following transaction appears after revocation: ```JSON @@ -279,7 +308,10 @@ For example, if the following transaction appears after revocation: "t": "ATTEST", "i": "EKtQ1lymrnrh3qv5S18PBzQ7ukHGFJ7EXkH7B22XEMIL", "d": "ELC5L3iBVD77d_MYbYGGCUQgqQBju1o4x1Ud-z2sL-ux", - "s": "1b" + "s": "1b", + "v": { + "v": "1.0" + } }, "1447": "{{someApplicationMetadata}}" } From 47f7207539882893110fe0e95e5f2d1f50b46b2c Mon Sep 17 00:00:00 2001 From: Kammerlo Date: Mon, 10 Nov 2025 16:03:04 +0100 Subject: [PATCH 29/31] docs: incorporated feedback --- CIP-????/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CIP-????/README.md b/CIP-????/README.md index 4c5d929454..9f0f1bee41 100644 --- a/CIP-????/README.md +++ b/CIP-????/README.md @@ -245,7 +245,7 @@ After verifying the validity of the credential chain with an ACDC verifier, ther 1. `EKtQ1lymrnrh3qv5S18PBzQ7ukHGFJ7EXkH7B22XEMIL` is the issuee of the metadata signer credential with a schema ID of `EJVgEQO8BEhGGM7GcAjlqoKG1upeuBZj9WjvjZo353sQ`. 2. The label attribute of the credential is `[1447]`. 3. The LEI attribute of the Legal Entity vLEI credential is `50670047U83746F70E20`. -4. The Qualified vLEI Issuer credential is issued by GLEIF’s External identifier, as listed [here](https://gleif-it.github.io/.well-known/). +4. The Qualified vLEI Issuer credential is issued by GLEIF’s External identifier - [more information](#root-of-trust-discovery) ### Creation of verifiable records The following is an attestation transaction for metadata label `1447`. From fc38ac931b54502d96609c2f84b07130a7b37442 Mon Sep 17 00:00:00 2001 From: Kammerlo Date: Tue, 11 Nov 2025 11:50:26 +0100 Subject: [PATCH 30/31] docs: typos --- CIP-????/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CIP-????/README.md b/CIP-????/README.md index 9f0f1bee41..b60cebb3c8 100644 --- a/CIP-????/README.md +++ b/CIP-????/README.md @@ -158,7 +158,7 @@ A reference to this event in a metadata transaction is structured as follows: "t": "AUTH_END", "s": "{{saidOfLeafCredentialSchema}}", "i": "{{aidOfSigner}}", - "c": "{{byteStream}}",, + "c": "{{byteStream}}", "v": { "v": "{{CIP Version String}}", "k": "{{KERI Version String}}", @@ -222,7 +222,7 @@ The following is the expected transaction format to publish the credential chain "v": { "v": "1.0", "k": "KERI10", - "a": "KERI10" + "a": "ACDC10" }, "m": { From 9338979bac58f221ca8dc3324e98c60290aa611e Mon Sep 17 00:00:00 2001 From: Robert Phair Date: Thu, 13 Nov 2025 12:52:25 +0530 Subject: [PATCH 31/31] add trailing CIP-0010 DB array comment (coding standard & CI validation) --- CIP-0010/registry.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CIP-0010/registry.json b/CIP-0010/registry.json index 8340fbb49e..134759359a 100644 --- a/CIP-0010/registry.json +++ b/CIP-0010/registry.json @@ -158,5 +158,5 @@ { "transaction_metadatum_label": "????", "description": "CIP-???? - KERI-backed metadata attestations" - } + }, ]