From dc0168911932f327de660037a4129088e7f5203e Mon Sep 17 00:00:00 2001 From: minikin Date: Wed, 20 Dec 2023 12:49:43 +0100 Subject: [PATCH 01/66] chore: wip --- docs/FLUTTER_INTEGRATION_TEST.md | 6 ++-- .../0005-flutter-app.md | 36 +++++++++++++++++++ 2 files changed, 38 insertions(+), 4 deletions(-) create mode 100644 docs/src/architecture/09_architecture_decisions/0005-flutter-app.md diff --git a/docs/FLUTTER_INTEGRATION_TEST.md b/docs/FLUTTER_INTEGRATION_TEST.md index e4eb7fc7c29..06cc4c62492 100644 --- a/docs/FLUTTER_INTEGRATION_TEST.md +++ b/docs/FLUTTER_INTEGRATION_TEST.md @@ -42,10 +42,8 @@ and select the appropriate history. #### Web -On Ubuntu you might be required to start chromedriver. -In a separate terminal run: - -`chromedriver --port=4444` +>On Ubuntu you might be required to start chromedriver. +>In a separate terminal run: `chromedriver --port=4444` Navigate to `catalyst_voices` and run: diff --git a/docs/src/architecture/09_architecture_decisions/0005-flutter-app.md b/docs/src/architecture/09_architecture_decisions/0005-flutter-app.md new file mode 100644 index 00000000000..aa179c79d69 --- /dev/null +++ b/docs/src/architecture/09_architecture_decisions/0005-flutter-app.md @@ -0,0 +1,36 @@ +--- + title: 0005 Catalyst Voices Frontend App Architecture + adr: + author: Oleksandr Prokhorenko + created: 30-Nov-2023 + status: proposed + tags: + - flutter +--- + +--- *This is a template ADR to be copied and completed when adding new ADR* --- + +## Context + +What is the issue that we're seeing that is motivating this decision or change? + +## Assumptions + +Anything that could cause problems if untrue now or later + +## Decision + +What is the change that we're proposing and/or doing? + +## Risks + +Anything that could cause malfunction, delay, or other negative impacts + +## Consequences + +What becomes easier or more difficult to do because of this change? + +## More Information + +Provide additional evidence/confidence for the decision outcome +Links to other decisions and resources might here appear as well. \ No newline at end of file From eccc9bf97ec7d82b7295d133b1ed69b5b0560b1c Mon Sep 17 00:00:00 2001 From: minikin Date: Thu, 21 Dec 2023 15:30:36 +0100 Subject: [PATCH 02/66] Update 0005-flutter-app.md --- .../0005-flutter-app.md | 32 ++++++++++++++----- 1 file changed, 24 insertions(+), 8 deletions(-) diff --git a/docs/src/architecture/09_architecture_decisions/0005-flutter-app.md b/docs/src/architecture/09_architecture_decisions/0005-flutter-app.md index aa179c79d69..90ebf708a6b 100644 --- a/docs/src/architecture/09_architecture_decisions/0005-flutter-app.md +++ b/docs/src/architecture/09_architecture_decisions/0005-flutter-app.md @@ -2,7 +2,7 @@ title: 0005 Catalyst Voices Frontend App Architecture adr: author: Oleksandr Prokhorenko - created: 30-Nov-2023 + created: 22-Dec-2023 status: proposed tags: - flutter @@ -12,25 +12,41 @@ ## Context -What is the issue that we're seeing that is motivating this decision or change? +For the Catalyst Voices Frontend App, our goal is to establish a structure that ensures scalability, maintainability, and a clear separation of concerns. With the complexity of voting events, it’s crucial to have an architecture that supports extensive functionality and easy adaptability to change. ## Assumptions -Anything that could cause problems if untrue now or later +* Clean Architecture will facilitate a clear separation of concerns across the app. +* The BLoC pattern, combined with ViewModels, will streamline state management across the app. +* Developers are or will become comfortable with reactive programming paradigms and Flutter’s Streams. +* The Flutter community will continue to support and evolve the BLoC pattern. +* The BLoC pattern will be sufficient to handle the app’s state management needs. ## Decision -What is the change that we're proposing and/or doing? +We have chosen to use BLoC with ViewModels, guided by Clean Architecture principles, for the development of the Catalyst Voices Frontend App. This approach will segregate the app into distinct layers - presentation, +domain, and data, with BLoC serving as the intermediary for state management and business logic. +The BLoC pattern will manage the app's state reactively, making it easier to handle complex state dependencies and asynchronous operations.The ViewModel layer will further aid in abstracting the presentation logic from BLoCs. + +TODO: Add diagram of the architecture ## Risks -Anything that could cause malfunction, delay, or other negative impacts +* Learning curve associated with Clean Architecture and BLoC pattern for developers not familiar with these concepts. +* Overhead in setting up and managing BLoCs and ViewModels for simpler UI components. +* Potential for boilerplate code, impacting readability and maintainability. ## Consequences -What becomes easier or more difficult to do because of this change? +* Enhanced maintainability and testability due to the separation of concerns. +* Greater flexibility in changing or extending the app’s features. +* Improved scalability, as new components can be added with minimal impact on existing code. +* A consistent structure across the app, aiding new developers in understanding the codebase. + ## More Information -Provide additional evidence/confidence for the decision outcome -Links to other decisions and resources might here appear as well. \ No newline at end of file +* Detailed documentation on Clean Architecture and how it applies to Flutter development. +* Documentation and best practices for implementing BLoC and ViewModels in Flutter. +* Examples of successful Flutter apps built using BLoC and Clean Architecture. +* Training sessions or resources for the team to get proficient in these architectural concepts. \ No newline at end of file From e00ae8315a8165fa9540542b0b5743c1ca0a29c2 Mon Sep 17 00:00:00 2001 From: minikin Date: Thu, 21 Dec 2023 16:20:11 +0100 Subject: [PATCH 03/66] Update 0005-flutter-app.md --- .../09_architecture_decisions/0005-flutter-app.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/src/architecture/09_architecture_decisions/0005-flutter-app.md b/docs/src/architecture/09_architecture_decisions/0005-flutter-app.md index 90ebf708a6b..5be5f129f74 100644 --- a/docs/src/architecture/09_architecture_decisions/0005-flutter-app.md +++ b/docs/src/architecture/09_architecture_decisions/0005-flutter-app.md @@ -12,7 +12,9 @@ ## Context -For the Catalyst Voices Frontend App, our goal is to establish a structure that ensures scalability, maintainability, and a clear separation of concerns. With the complexity of voting events, it’s crucial to have an architecture that supports extensive functionality and easy adaptability to change. +For the Catalyst Voices Frontend App, our goal is to establish a structure that ensures scalability, +maintainability, and a clear separation of concerns. With the complexity of voting events, +it’s crucial to have an architecture that supports extensive functionality and easy adaptability to change. ## Assumptions @@ -24,11 +26,11 @@ For the Catalyst Voices Frontend App, our goal is to establish a structure that ## Decision -We have chosen to use BLoC with ViewModels, guided by Clean Architecture principles, for the development of the Catalyst Voices Frontend App. This approach will segregate the app into distinct layers - presentation, -domain, and data, with BLoC serving as the intermediary for state management and business logic. +We have chosen to use BLoC with ViewModels, guided by Clean Architecture principles, +for the development of the Catalyst Voices Frontend App. This approach will segregate the app into distinct layers - presentation, domain, and data, with BLoC serving as the intermediary for state management and business logic. The BLoC pattern will manage the app's state reactively, making it easier to handle complex state dependencies and asynchronous operations.The ViewModel layer will further aid in abstracting the presentation logic from BLoCs. -TODO: Add diagram of the architecture +TODO: Add diagram of the architecture and how the different layers interact. ## Risks @@ -43,10 +45,12 @@ TODO: Add diagram of the architecture * Improved scalability, as new components can be added with minimal impact on existing code. * A consistent structure across the app, aiding new developers in understanding the codebase. - ## More Information +TODO: Add links to resources + * Detailed documentation on Clean Architecture and how it applies to Flutter development. +* [The Clean Architecture](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html) * Documentation and best practices for implementing BLoC and ViewModels in Flutter. * Examples of successful Flutter apps built using BLoC and Clean Architecture. * Training sessions or resources for the team to get proficient in these architectural concepts. \ No newline at end of file From 42c37554619eb6d3e3e7294f5b24902343ed9803 Mon Sep 17 00:00:00 2001 From: minikin Date: Fri, 22 Dec 2023 14:26:35 +0100 Subject: [PATCH 04/66] Update 0005-flutter-app.md --- .../09_architecture_decisions/0005-flutter-app.md | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/docs/src/architecture/09_architecture_decisions/0005-flutter-app.md b/docs/src/architecture/09_architecture_decisions/0005-flutter-app.md index 5be5f129f74..9c384dc7d7b 100644 --- a/docs/src/architecture/09_architecture_decisions/0005-flutter-app.md +++ b/docs/src/architecture/09_architecture_decisions/0005-flutter-app.md @@ -12,7 +12,7 @@ ## Context -For the Catalyst Voices Frontend App, our goal is to establish a structure that ensures scalability, +Our goal for the Catalyst Voices Frontend App is to establish a structure that ensures scalability, maintainability, and a clear separation of concerns. With the complexity of voting events, it’s crucial to have an architecture that supports extensive functionality and easy adaptability to change. @@ -47,10 +47,7 @@ TODO: Add diagram of the architecture and how the different layers interact. ## More Information -TODO: Add links to resources - -* Detailed documentation on Clean Architecture and how it applies to Flutter development. * [The Clean Architecture](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html) -* Documentation and best practices for implementing BLoC and ViewModels in Flutter. -* Examples of successful Flutter apps built using BLoC and Clean Architecture. -* Training sessions or resources for the team to get proficient in these architectural concepts. \ No newline at end of file +* [BLoC Pattern - DartConf 2018](https://youtu.be/PLHln7wHgPE?si=QJ8hXOCWz2WIYFye) +* [BLoC Pub Documentation](https://bloclibrary.dev/) +* [Flutter BLoC Examples](https://github.com/felangel/bloc/tree/master/examples) From 3183dc21616b513486b15f7b0d6909e7e28bd1c5 Mon Sep 17 00:00:00 2001 From: minikin Date: Mon, 25 Dec 2023 11:39:18 +0100 Subject: [PATCH 05/66] Update 0005-flutter-app.md --- .../0005-flutter-app.md | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/docs/src/architecture/09_architecture_decisions/0005-flutter-app.md b/docs/src/architecture/09_architecture_decisions/0005-flutter-app.md index 9c384dc7d7b..7d96f32cbed 100644 --- a/docs/src/architecture/09_architecture_decisions/0005-flutter-app.md +++ b/docs/src/architecture/09_architecture_decisions/0005-flutter-app.md @@ -27,10 +27,20 @@ it’s crucial to have an architecture that supports extensive functionality and ## Decision We have chosen to use BLoC with ViewModels, guided by Clean Architecture principles, -for the development of the Catalyst Voices Frontend App. This approach will segregate the app into distinct layers - presentation, domain, and data, with BLoC serving as the intermediary for state management and business logic. -The BLoC pattern will manage the app's state reactively, making it easier to handle complex state dependencies and asynchronous operations.The ViewModel layer will further aid in abstracting the presentation logic from BLoCs. +for the development of the Catalyst Voices Frontend App. +This approach will segregate the app into distinct layers - presentation, domain, and data, +with BLoC serving as the intermediary for state management and business logic. +The BLoC pattern will manage the app's state reactively, +making it easier to handle complex state dependencies and asynchronous operations. +The ViewModel layer will further aid in abstracting the presentation logic from BLoCs. + + + + + +### Practical Example + -TODO: Add diagram of the architecture and how the different layers interact. ## Risks From d23779b77b6ffc0ac152c636e10cbbf99976f7a9 Mon Sep 17 00:00:00 2001 From: minikin Date: Wed, 27 Dec 2023 16:44:04 +0100 Subject: [PATCH 06/66] Update 0005-flutter-app.md --- .../0005-flutter-app.md | 46 ++++++++++++++++++- 1 file changed, 44 insertions(+), 2 deletions(-) diff --git a/docs/src/architecture/09_architecture_decisions/0005-flutter-app.md b/docs/src/architecture/09_architecture_decisions/0005-flutter-app.md index 7d96f32cbed..29e3496c5c7 100644 --- a/docs/src/architecture/09_architecture_decisions/0005-flutter-app.md +++ b/docs/src/architecture/09_architecture_decisions/0005-flutter-app.md @@ -26,7 +26,7 @@ it’s crucial to have an architecture that supports extensive functionality and ## Decision -We have chosen to use BLoC with ViewModels, guided by Clean Architecture principles, +We have chosen to use BLoC pattern alongside ViewModels, guided by Clean Architecture principles, for the development of the Catalyst Voices Frontend App. This approach will segregate the app into distinct layers - presentation, domain, and data, with BLoC serving as the intermediary for state management and business logic. @@ -34,7 +34,49 @@ The BLoC pattern will manage the app's state reactively, making it easier to handle complex state dependencies and asynchronous operations. The ViewModel layer will further aid in abstracting the presentation logic from BLoCs. - +```mermaid +--- +title: Catalyst Voices Fronted Architecture +--- +flowchart LR + subgraph id1 [BLoC pattern in conjunction with ViewModels steered by the principles of Clean Architecture.] + subgraph id2 [Application Layer] + direction LR + subgraph id3 [Presentation Layer] + direction RL + subgraph id4 [Connect Wallet Screen] + id01[Widgets] + end + subgraph id5 [View All Events Screen] + id02[Widgets] + end + subgraph id6 [Settings Screen] + id03[Widgets] + end + end + subgraph id5555 [Business Layer] + direction RL + subgraph id7 [Connect Wallet Bloc] + end + subgraph id8 [View All Events Bloc] + end + subgraph id9 [Settings Bloc] + end + end + end + subgraph Domain Layer + cv1 + cv2 + end + subgraph Data Layer + cssdd1 + cdd2 + end + end + id4 <--> id7 + id5 <--> id8 + id6 <--> id9 +``` From 16bf4a2a8e84272511962118b6be90b15d3157e2 Mon Sep 17 00:00:00 2001 From: minikin Date: Wed, 27 Dec 2023 17:41:44 +0100 Subject: [PATCH 07/66] Update 0005-flutter-app.md --- .../0005-flutter-app.md | 71 ++++++++++++------- 1 file changed, 45 insertions(+), 26 deletions(-) diff --git a/docs/src/architecture/09_architecture_decisions/0005-flutter-app.md b/docs/src/architecture/09_architecture_decisions/0005-flutter-app.md index 29e3496c5c7..f429719ea8c 100644 --- a/docs/src/architecture/09_architecture_decisions/0005-flutter-app.md +++ b/docs/src/architecture/09_architecture_decisions/0005-flutter-app.md @@ -8,8 +8,6 @@ - flutter --- ---- *This is a template ADR to be copied and completed when adding new ADR* --- - ## Context Our goal for the Catalyst Voices Frontend App is to establish a structure that ensures scalability, @@ -38,44 +36,65 @@ The ViewModel layer will further aid in abstracting the presentation logic from --- title: Catalyst Voices Fronted Architecture --- -flowchart LR - subgraph id1 [BLoC pattern in conjunction with ViewModels steered by the principles of Clean Architecture.] - subgraph id2 [Application Layer] +flowchart TB + subgraph id1 [BLoC pattern in conjunction with ViewModels steered by the principles of Clean Architecture] + subgraph al01 [Application Layer] + direction LR + subgraph al02 [Presentation Layer] direction LR - subgraph id3 [Presentation Layer] - direction RL - subgraph id4 [Connect Wallet Screen] - id01[Widgets] + subgraph al03 [Connect Wallet Screen] + w1[Widgets] end - subgraph id5 [View All Events Screen] - id02[Widgets] + subgraph al04 [View All Events Screen] + w2[Widgets] end - subgraph id6 [Settings Screen] - id03[Widgets] + subgraph al05 [Settings Screen] + w3[Widgets] end end - subgraph id5555 [Business Layer] - direction RL - subgraph id7 [Connect Wallet Bloc] + subgraph bl01 [Business Layer] + direction LR + subgraph bl02 [Connect Wallet Bloc] + vm01[State <---> Event <---> ViewModel] end - subgraph id8 [View All Events Bloc] + subgraph bl03 [View All Events Bloc] + vm02[State <---> Event <---> ViewModel] end - subgraph id9 [Settings Bloc] + subgraph bl04 [Settings Bloc] + vm03[State <---> Event <---> ViewModel] end end end - subgraph Domain Layer - cv1 - cv2 + subgraph dl01 [Domain Layer] + direction RL + subgraph dl02 [Connect Wallet Repository] + end + subgraph dl03 [Events Repository] + end + subgraph dl04 [User Repository] + end end subgraph Data Layer - cssdd1 - cdd2 + direction RL + subgraph dl05 [Connect Wallet API] + end + subgraph dl06 [Catalyst Events API] + end + subgraph dl07 [Local Storage] + end end end - id4 <--> id7 - id5 <--> id8 - id6 <--> id9 + al03 <--> bl02 + al04 <--> bl03 + al05 <--> bl04 + bl02 <--> dl02 + bl03 <--> dl03 + bl04 <--> dl04 + dl02 <--> dl05 + dl02 <--> dl07 + dl03 <--> dl06 + dl03 <--> dl07 + dl04 <--> dl07 ``` From 1b980f2b3f6f20eec36ecfe902d6e50a090b3f2e Mon Sep 17 00:00:00 2001 From: minikin Date: Wed, 27 Dec 2023 17:44:01 +0100 Subject: [PATCH 08/66] Update 0005-flutter-app.md --- .../architecture/09_architecture_decisions/0005-flutter-app.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/src/architecture/09_architecture_decisions/0005-flutter-app.md b/docs/src/architecture/09_architecture_decisions/0005-flutter-app.md index f429719ea8c..e5d3c69ce4f 100644 --- a/docs/src/architecture/09_architecture_decisions/0005-flutter-app.md +++ b/docs/src/architecture/09_architecture_decisions/0005-flutter-app.md @@ -122,3 +122,4 @@ flowchart TB * [BLoC Pattern - DartConf 2018](https://youtu.be/PLHln7wHgPE?si=QJ8hXOCWz2WIYFye) * [BLoC Pub Documentation](https://bloclibrary.dev/) * [Flutter BLoC Examples](https://github.com/felangel/bloc/tree/master/examples) +* [ViewModel overview](https://developer.android.com/topic/libraries/architecture/viewmodel) From bcc4891835e1399d67ed6e4a135bb7cb4df2d78e Mon Sep 17 00:00:00 2001 From: minikin Date: Wed, 27 Dec 2023 17:46:21 +0100 Subject: [PATCH 09/66] Update 0005-flutter-app.md --- .../09_architecture_decisions/0005-flutter-app.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/src/architecture/09_architecture_decisions/0005-flutter-app.md b/docs/src/architecture/09_architecture_decisions/0005-flutter-app.md index e5d3c69ce4f..fa1bf0645db 100644 --- a/docs/src/architecture/09_architecture_decisions/0005-flutter-app.md +++ b/docs/src/architecture/09_architecture_decisions/0005-flutter-app.md @@ -97,8 +97,6 @@ flowchart TB dl04 <--> dl07 ``` - - ### Practical Example @@ -121,5 +119,6 @@ flowchart TB * [The Clean Architecture](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html) * [BLoC Pattern - DartConf 2018](https://youtu.be/PLHln7wHgPE?si=QJ8hXOCWz2WIYFye) * [BLoC Pub Documentation](https://bloclibrary.dev/) -* [Flutter BLoC Examples](https://github.com/felangel/bloc/tree/master/examples) -* [ViewModel overview](https://developer.android.com/topic/libraries/architecture/viewmodel) +* [Flutter BLoC Examples](https://github.com/felangel/bloc/tree/master/examples) +* [So What Exactly is a View-Model?](https://www.infoq.com/articles/View-Model-Definition/) +* [ViewModel Overview from Android Developers](https://developer.android.com/topic/libraries/architecture/viewmodel) From e63d75cfbe7f6caa6f830b67503acf3428662ad7 Mon Sep 17 00:00:00 2001 From: minikin Date: Fri, 29 Dec 2023 15:18:24 +0100 Subject: [PATCH 10/66] Update 0005-flutter-app.md --- .../0005-flutter-app.md | 55 ++++++++++++++++++- 1 file changed, 52 insertions(+), 3 deletions(-) diff --git a/docs/src/architecture/09_architecture_decisions/0005-flutter-app.md b/docs/src/architecture/09_architecture_decisions/0005-flutter-app.md index fa1bf0645db..df9d306deb1 100644 --- a/docs/src/architecture/09_architecture_decisions/0005-flutter-app.md +++ b/docs/src/architecture/09_architecture_decisions/0005-flutter-app.md @@ -97,9 +97,57 @@ flowchart TB dl04 <--> dl07 ``` -### Practical Example - - +### Maintain Uniformity + +To the established patterns of the team. Avoid bypassing the structured layers. +Ensure each layer maintains a clear relationship hierarchy, preventing direct interactions between non-adjacent layers. +For instance, the presentation layer should never directly communicate with the data layer's APIs. +Maintain the hierarchy where the data layer is dependent on the domain layer across all feature development. + +Effective naming conventions are crucial for ease of navigation within a project. +While naming is flexible (some may refer to the data layer as infrastructure), +consistency in these names is essential for maintaining a clear architectural understanding. +Inconsistency can lead to a disorganized and challenging codebase, potentially causing confusion among team members. +It's vital to adhere to the established guidelines within the codebase to avoid these issues. + +```txt +├── catalyst_voices +| ├── libs +│ │ ├── app +│ │ │ └── app.dart +| | | └── utils.dart +| | └── configs +| | | └── app_bloc_observer.dart +| | | └── bootstrap.dart +| | | └── main_dev.dart +| | | └── main_prod.dart +| | | └── main_preprod.dart +| | | └── main_qa.dart +│ │ └── connect_wallet +│ │ | ├── connect_wallet_page.dart +| | | └── wallet_list_item.dart +│ │ | └── wallets_list.dart +| | └── events +| | | └── events_page.dart +| | | └── events_list_item.dart +| | | └── other_event_widgets.dart +│ │ ├── setting +│ │ | ├── settings_page.dart +| | | └── user_widget.dart +| | | └── app_settings.dart +│ ├── packages +│ │ ├── catalyst_voices_assets +│ │ ├── catalyst_voices_blocs +│ │ ├── catalyst_voices_localization +│ │ ├── catalyst_voices_models +│ │ ├── catalyst_voices_repositories +│ │ ├── catalyst_voices_services +│ │ ├── catalyst_voices_models +│ │ ├── catalyst_voices_shared +│ │ ├── catalyst_voices_view_models +├── pubspec.lock +├── pubspec.yaml +``` ## Risks @@ -117,6 +165,7 @@ flowchart TB ## More Information * [The Clean Architecture](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html) +* [SOLID](https://www.digitalocean.com/community/conceptual-articles/s-o-l-i-d-the-first-five-principles-of-object-oriented-design) * [BLoC Pattern - DartConf 2018](https://youtu.be/PLHln7wHgPE?si=QJ8hXOCWz2WIYFye) * [BLoC Pub Documentation](https://bloclibrary.dev/) * [Flutter BLoC Examples](https://github.com/felangel/bloc/tree/master/examples) From 0539ac955248f37466551a146a31b738bbca1716 Mon Sep 17 00:00:00 2001 From: minikin Date: Fri, 29 Dec 2023 15:25:25 +0100 Subject: [PATCH 11/66] Update 0005-flutter-app.md --- .../09_architecture_decisions/0005-flutter-app.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/src/architecture/09_architecture_decisions/0005-flutter-app.md b/docs/src/architecture/09_architecture_decisions/0005-flutter-app.md index df9d306deb1..346feafe040 100644 --- a/docs/src/architecture/09_architecture_decisions/0005-flutter-app.md +++ b/docs/src/architecture/09_architecture_decisions/0005-flutter-app.md @@ -11,7 +11,8 @@ ## Context Our goal for the Catalyst Voices Frontend App is to establish a structure that ensures scalability, -maintainability, and a clear separation of concerns. With the complexity of voting events, +maintainability, and a clear separation of concerns. +With the complexity of voting events, it’s crucial to have an architecture that supports extensive functionality and easy adaptability to change. ## Assumptions @@ -99,7 +100,8 @@ flowchart TB ### Maintain Uniformity -To the established patterns of the team. Avoid bypassing the structured layers. +To the established patterns of the team. +Avoid bypassing the structured layers. Ensure each layer maintains a clear relationship hierarchy, preventing direct interactions between non-adjacent layers. For instance, the presentation layer should never directly communicate with the data layer's APIs. Maintain the hierarchy where the data layer is dependent on the domain layer across all feature development. @@ -168,6 +170,6 @@ It's vital to adhere to the established guidelines within the codebase to avoid * [SOLID](https://www.digitalocean.com/community/conceptual-articles/s-o-l-i-d-the-first-five-principles-of-object-oriented-design) * [BLoC Pattern - DartConf 2018](https://youtu.be/PLHln7wHgPE?si=QJ8hXOCWz2WIYFye) * [BLoC Pub Documentation](https://bloclibrary.dev/) -* [Flutter BLoC Examples](https://github.com/felangel/bloc/tree/master/examples) +* [Flutter BLoC Examples](https://github.com/felangel/bloc/tree/master/examples) * [So What Exactly is a View-Model?](https://www.infoq.com/articles/View-Model-Definition/) * [ViewModel Overview from Android Developers](https://developer.android.com/topic/libraries/architecture/viewmodel) From 07ad50cc66a37e113ea6cff796ab9cc876573905 Mon Sep 17 00:00:00 2001 From: minikin Date: Wed, 3 Jan 2024 13:58:50 +0100 Subject: [PATCH 12/66] Update 0005-flutter-app.md --- .../architecture/09_architecture_decisions/0005-flutter-app.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/src/architecture/09_architecture_decisions/0005-flutter-app.md b/docs/src/architecture/09_architecture_decisions/0005-flutter-app.md index 346feafe040..47e3295bf47 100644 --- a/docs/src/architecture/09_architecture_decisions/0005-flutter-app.md +++ b/docs/src/architecture/09_architecture_decisions/0005-flutter-app.md @@ -34,9 +34,6 @@ making it easier to handle complex state dependencies and asynchronous operation The ViewModel layer will further aid in abstracting the presentation logic from BLoCs. ```mermaid ---- -title: Catalyst Voices Fronted Architecture ---- flowchart TB subgraph id1 [BLoC pattern in conjunction with ViewModels steered by the principles of Clean Architecture] subgraph al01 [Application Layer] From ec8ea17dc553baed5d8c00a389af31279a501cbd Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Thu, 4 Jan 2024 16:00:15 +0700 Subject: [PATCH 13/66] docs(docs): Use latest docs builders and fix concepts page --- docs/Earthfile | 6 +++--- docs/src/architecture/08_concepts/.pages | 1 + 2 files changed, 4 insertions(+), 3 deletions(-) create mode 100644 docs/src/architecture/08_concepts/.pages diff --git a/docs/Earthfile b/docs/Earthfile index e257d603446..a10978793b0 100644 --- a/docs/Earthfile +++ b/docs/Earthfile @@ -6,7 +6,7 @@ VERSION 0.7 # Copy all the source we need to build the docs src: # Common src setup - DO github.com/input-output-hk/catalyst-ci/earthly/docs:v2.0.11+SRC + DO github.com/input-output-hk/catalyst-ci/earthly/docs:v2.0.16+SRC # Now copy into that any artifacts we pull from the builds. COPY --dir ../+repo-docs/repo /docs/includes @@ -21,12 +21,12 @@ src: docs: FROM +src - DO github.com/input-output-hk/catalyst-ci/earthly/docs:v2.0.11+BUILD + DO github.com/input-output-hk/catalyst-ci/earthly/docs:v2.0.16+BUILD # Make a locally runable container that can serve the docs. local: # Build a self contained service to show built docs locally. - DO github.com/input-output-hk/catalyst-ci/earthly/docs:v2.0.11+PACKAGE + DO github.com/input-output-hk/catalyst-ci/earthly/docs:v2.0.16+PACKAGE # Copy the static pages into the container COPY +docs/ /usr/share/nginx/html diff --git a/docs/src/architecture/08_concepts/.pages b/docs/src/architecture/08_concepts/.pages new file mode 100644 index 00000000000..582fe53ade2 --- /dev/null +++ b/docs/src/architecture/08_concepts/.pages @@ -0,0 +1 @@ +title: Concepts \ No newline at end of file From d6e5ce88f23c4b25bb7442094f119b2841ed7f35 Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Thu, 11 Jan 2024 20:08:31 +0700 Subject: [PATCH 14/66] docs(cips): Start drafting the CIPS for milestone 2 --- .../draft-cips/role-registration/cip-xxxx.md | 74 +++++++++++++++---- 1 file changed, 59 insertions(+), 15 deletions(-) diff --git a/docs/src/catalyst-standards/draft-cips/role-registration/cip-xxxx.md b/docs/src/catalyst-standards/draft-cips/role-registration/cip-xxxx.md index 62dc1898982..1d4352f86c2 100644 --- a/docs/src/catalyst-standards/draft-cips/role-registration/cip-xxxx.md +++ b/docs/src/catalyst-standards/draft-cips/role-registration/cip-xxxx.md @@ -9,27 +9,18 @@ Implementors: [] Discussions: - https://github.com/cardano-foundation/cips/pulls/? Created: 2023-10-24 -License: CC-BY-4.0 +License: CC-BY-4.0 / Apache 2.0 --- - - # Role Based Access Control Registration ## Abstract +dApps such as Project Catalyst need robust, secure and extensible means for users to register under various roles +and for the dApp to be able to validate actions against those roles. +While these Role based registrations are required for future functionality of Project Catalyst, they are also +intended to be generally useful to any dApp with User roles. ## Motivation: why is this CIP necessary? +CIP-36 contains a limited form of role registration limited to voters and dreps. + +However, Project Catalyst has a large (and growing) number of roles identified in the system, all of +which can benefit from on-chain registration. + +A non-exhaustive list of the roles Project Catalyst needs to identify on-chain are: + +1. Proposers. +2. Co-Proposers. +3. Proposal Reviewers. +4. Voters. +5. Representative voters. +6. Tally committee members. +7. Administrators. +8. Audit committee members. + +Individual dApps may have their own unique list of roles they wish users to register for. +Roles are such that an individual user may hold multiple roles, one of the purposes of this +CIP is to allow the user to unambiguously assert they are acting in the capacity of a selected role. + +CIP-36 offers a "purpose" field, but offers no way to manage it, and offers no way to allow it to be used unambiguously. +The "purpose" field therefore is insufficient for the needs of identifying roles. + +CIP-36 also does not allow the voting key to be validated. +This makes it impossible to determine if the registration voting key is usable, and owned by the registering user, or has +been duplicated from another registration on-chain or is just a random number. + +It also offers no way to identify the difference between a voter registering for themselves, and a voter registering to be a dRep. + +These are some of the key reasons, CIP-36 is insufficient for future Project Catalyst needs. + +Registering for various roles and having role specific keys is generally useful for dApps, so while this CIP is +motivated to solve problems with Project Catalyst, it is also intended to be generally applicable to other dApps. + ## Specification +Role registration is achieved by using two metadata records attached to the same transaction. + +### Metadata Labels + +| Label | Description | +| --- | --- | +| 72220 | The RBAC Metadata Label | +| 72221 | The RBAC Metadata witness set Label | + +Both pieces of metadata must be present for the registration to be valid. + +Note: **7222 is RBAC when decoded using the telephone ITU E.161 standard** + ## Rationale: how does this CIP achieve its goals? ## Copyright - + +This CIP is licensed under [CC-BY-4.0] + +Code samples and reference material are licensed under [Apache 2.0] + +[CC-BY-4.0]: https://creativecommons.org/licenses/by/4.0/legalcode +[Apache 2.0]: https://www.apache.org/licenses/LICENSE-2.0.html From 211293dcc9607d5329612e15c5feed291b8f3b0b Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Fri, 12 Jan 2024 21:00:00 +0700 Subject: [PATCH 15/66] docs(cips): More text for RBAC metadata draft --- .../draft-cips/role-registration/cip-xxxx.md | 76 ++++++++++++++++++- 1 file changed, 72 insertions(+), 4 deletions(-) diff --git a/docs/src/catalyst-standards/draft-cips/role-registration/cip-xxxx.md b/docs/src/catalyst-standards/draft-cips/role-registration/cip-xxxx.md index 1d4352f86c2..e2b599a6795 100644 --- a/docs/src/catalyst-standards/draft-cips/role-registration/cip-xxxx.md +++ b/docs/src/catalyst-standards/draft-cips/role-registration/cip-xxxx.md @@ -74,15 +74,81 @@ Role registration is achieved by using two metadata records attached to the same ### Metadata Labels -| Label | Description | +| Metadata Label | Description | | --- | --- | -| 72220 | The RBAC Metadata Label | -| 72221 | The RBAC Metadata witness set Label | +| `7222` | The RBAC Metadata Label | +| `7223` | The RBAC Metadata witness set Label | -Both pieces of metadata must be present for the registration to be valid. +Both pieces of metadata must be present in the same transaction for the registration to be valid. + +`7222` AND `7223` define this Metadata as being Role Registration Metadata. +These Metadata key should not be used for another purpose. Note: **7222 is RBAC when decoded using the telephone ITU E.161 standard** +### Metadata Encoding + +* The metadata will be encoded with [CBOR]. +* The [CBOR] metadata will be encoded strictly according to [CBOR - Core Deterministic Encoding Requirements]. +* There **MUST NOT** be any duplicate keys in a map. +* UTF-8 strings **MUST** be valid UTF-8. +* Tags **MUST NOT** be used unless specified in the specification. +* Any Tags defined in the specification are **REQUIRED**, and they **MUST** be present in the encoded data. +* Fields which should be tagged, but which are not tagged will be considered invalid. + +These validity checks apply only to the encoding and decoding of the metadata itself. +There are other validity requirements based on the role registration data itself. +Each dApp may have further validity requirements beyond those stated herein. + +### High level overview of Role Registration metadata + +At a high level, Role registration will collect the following data: + +1. A [role public key or non-empty group of role public keys](); +2. A [stake address for the network that this transaction is submitted to](); +3. An *Optional* [Shelley payment address](). +4. A [nonce]() that identifies that most recent registration. +5. The [purpose]() of the registration. +6. A [dApp ID]() which defines the dApp the registration belongs to. +6. An *Optional* [expiry timestamp](). +7. Optional dApp defined [extended registration metadata](). + +The formal specification for the `7222` Metadata is [CIPxxxx Metadata CDDL][]. + +Informally, all Registrations follow the same generalized Format: + +```cbor +7222: { + // Role Public Key or Role Public Key Array + 1: h'a6a3c0447aeb9cc54cf6422ba32b294e5e1c3ef6d782f2acff4a70694c4d1663' or , + [[h'A71A8700248D4C91E01A2A2CB5F4F0E664F084EB761C6792AEDD28160C1E403C', 50], [h'C606D983C5545800FAF20519D21988AA0A13271BA12BA9A8643FCFAD58697C97', 50]] + // Stake Public Key + 2: h'ad4b948699193634a39dd56f779a2951a24779ad52aa7916f6912b8ec4702cee', + // Payment Address + 3: h'00588e8e1d18cba576a4d35758069fe94e53f638b6faf7c07b8abd2bc5c5cdee47b60edc7772855324c85033c638364214cbfc6627889f81c4', + // nonce + 4: 5479467, + // Purpose + 5: 0, + // dApp ID + 6: h'', + // Expires - Optional + 7: 0, + // dApp Defined Metadata - Optional + 100: +} +``` + +Keys between `8` and `99` are reserved for any future extensions to this specification. +They must not be defined by any dApp for private use. +These + +Keys above `100` are reserved for dApp specific use, and may be defined either formally or informally by any dApp. +General parsers of this data should accept, but not otherwise interpret keys `100`+ unless they specifically understand +the requirements of the identified dApp. + +### High level overview of the Role Registration witness data + ## Rationale: how does this CIP achieve its goals? + dApps such as Project Catalyst need robust, secure and extensible means for users to register under various roles and for the dApp to be able to validate actions against those roles. While these Role based registrations are required for future functionality of Project Catalyst, they are also intended to be generally useful to any dApp with User roles. ## Motivation: why is this CIP necessary? - CIP-36 contains a limited form of role registration limited to voters and dreps. However, Project Catalyst has a large (and growing) number of roles identified in the system, all of which can benefit from on-chain registration. -A non-exhaustive list of the roles Project Catalyst needs to identify on-chain are: +A non-exhaustive example list of the roles Project Catalyst needs to identify securely are: 1. Proposers. 2. Co-Proposers. @@ -46,7 +42,7 @@ A non-exhaustive list of the roles Project Catalyst needs to identify on-chain a Individual dApps may have their own unique list of roles they wish users to register for. Roles are such that an individual user may hold multiple roles, one of the purposes of this -CIP is to allow the user to unambiguously assert they are acting in the capacity of a selected role. +CIP is to allow the user to unambiguously assert they are acting in the capacity of a selected role. CIP-36 offers a "purpose" field, but offers no way to manage it, and offers no way to allow it to be used unambiguously. The "purpose" field therefore is insufficient for the needs of identifying roles. @@ -63,12 +59,6 @@ Registering for various roles and having role specific keys is generally useful motivated to solve problems with Project Catalyst, it is also intended to be generally applicable to other dApps. ## Specification - Role registration is achieved by using two metadata records attached to the same transaction. @@ -136,7 +126,8 @@ Informally, all Registrations follow the same generalized Format (Non-Normative) // Role 5: 0, // dApp ID (UUID or ULID) - 6: h'', + 6: #6.37 h'a3c12b1c98af4ee8b54278e77906c0fc'; or // UUID + #6.32770 h'018d1d2acaf04486be189dbc5ae35e51', // ULID // Expires - Optional 7: 0, // dApp Defined Metadata - Optional @@ -157,7 +148,7 @@ the requirements of the identified dApp. Subkey 1 is either: * A Single [Role Specific Public Key](#subkey-1---role-key---single-role-specific-public-key); OR -* A [Optionally Weighted List of Role Specific Public Keys](#grouped-role-registration-format). +* A [Optionally Weighted List of Role Specific Public Keys](#subkey-1---role-key---list-of-role-keys). #### SubKey 1 - Role Key - Single Role Specific Public Key @@ -210,39 +201,43 @@ It also provides a mechanism to unambiguously identify the role being asserted w The Role Specific key derivation path must start with a specific segment: Path based key derivation is limited to 31 bits, per path component. -The [dApp ID]() is 128 bits. +The [dApp ID] is 128 bits. It is required that the Role key be, as far as practically possible, unique amongst dApps. This is to prevent a Role from one dApp being misused by another, either intentionally or inadvertently. -The [dApp ID]() will be reduced to 31 bits by using Blake2B with a 31 bit digest over the [dApp ID](). -While 31 bits is small, and could be subject to a collision attack, the intention here is not to prevent -deliberately contrived collisions but to disambiguate dApps under normal circumstances. -As the [dApp ID]() is not controllable, a malicious dApp could simply use the same dApp ID as another. -Therefore it is not possible to protect against a collision and the [dApp ID]() is not a security mechanism -in any event. - -However key derivation is limited to 31 bits, accordingly, the [dApp ID][] will be hashed with Blake2B and a +However key derivation is limited to 31 bits, accordingly, the [dApp ID] will be hashed with Blake2B and a 31 bit digest will be produced. The aim is to as far as practical cause dApps to have distinct Role keys under normal circumstances. -`m / 7222' / 1815' / account' / chain' / blake2b_31(dApp ID) / role` +`m / 7222' / 1815' / account' / chain' / hash(dApp ID) / role` * `7222'` : The registration metadata field key from this CIP. * `1815'` : The year Ada Lovelace was born - Identifies this key as being for Cardano. * `account'` : The voters account * `chain'` : The chain on which the voter is registering. -* `blake2b_31(uuid)` : The [dApp ID]() +* `hash(dapp ID)` : The [hashed](#hashdapp-id) [dApp ID] * `role` : The role being registered for. -Note: It is specifically required that the Role Key NOT CHANGE for registrations made from the same wallet for the same dApp UUID/Purpose. -This is because its possible to make both single and array role registrations, and its critical the key be the same regardless of which is used. +Note: It is specifically required that the Role Key NOT CHANGE for the same dApp UUID/Purpose for any compliant Wallet. +This is because its possible to make both single and array role registrations, and its critical the key be the same in these. +It also critical that the Role keys be freely transferable and recoverable across wallets. The necessity of this will be expanded on when the witness is discussed below. -If the wallet does not use path based key derivation it is Essential that: +##### hash(dapp ID) + +The [dApp ID] will be reduced to 31 bits by using Blake2B with a 32 bit digest over the [dApp ID]. -* Role Specific Public Keys do not change from registration to registration for the same [dApp UUID][dApp-UUID]/Purpose. -* Role Specific Public Keys are not the same for different Purposes for a UUID. -* It is acceptable, though undesirable, for different [dApp UUID's][dApp-UUID] to use the same Role Specific Public Keys. +To ensure the hardening bit is not set, the high bit of the resultant hash will be forced to 0. + +```text + hash(dapp ID) == blake2b_32(dapp ID) & 0x7FFFFFFF +``` + +While 31 bits is small, and could be subject to a collision attack, the intention here is not to prevent +deliberately contrived collisions but to disambiguate dApps under normal circumstances. +As the [dApp ID] is not controllable, a malicious dApp could simply use the same dApp ID as another. +Therefore it is not possible to protect against a collision and the [dApp ID] is not a security mechanism +in any event. #### SubKey 1 - Role Key - List of Role Keys @@ -540,3 +535,4 @@ Code samples and reference material are licensed under [Apache 2.0] [Apache 2.0]: https://www.apache.org/licenses/LICENSE-2.0.html [CBOR]: https://www.rfc-editor.org/rfc/rfc8949.html [CBOR - Core Deterministic Encoding Requirements]: https://www.rfc-editor.org/rfc/rfc8949.html#section-4.2.1 +[CIP0003]: https://cips.cardano.org/cip/CIP-0003 From 0680e0735000dc2ffbd756266cf58d47b5a390f4 Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Thu, 18 Jan 2024 23:14:34 +0700 Subject: [PATCH 19/66] docs(cips): fix ulid spec binary encoding reference --- docs/src/catalyst-standards/cbor_tags/ulid.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/catalyst-standards/cbor_tags/ulid.md b/docs/src/catalyst-standards/cbor_tags/ulid.md index 74bc1dbbe20..2ba79b7b635 100644 --- a/docs/src/catalyst-standards/cbor_tags/ulid.md +++ b/docs/src/catalyst-standards/cbor_tags/ulid.md @@ -27,4 +27,4 @@ RFC 7049, October 2013. Steven Johnson [ULID]: https://github.com/ulid/spec/blob/master/README.md -[ULID Binary Layout]: https://github.com/ulid/spec/blob/master/README.md +[ULID Binary Layout]: https://github.com/ulid/spec/tree/master#binary-layout-and-byte-order From d849fdee8354b3c23fc7a063eab9f72c825bbfc7 Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Thu, 18 Jan 2024 23:15:28 +0700 Subject: [PATCH 20/66] docs(cips): Add a tag to the epoch time. --- .../draft-cips/role-registration/cip-xxxx.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/catalyst-standards/draft-cips/role-registration/cip-xxxx.md b/docs/src/catalyst-standards/draft-cips/role-registration/cip-xxxx.md index 5034b9ae3d6..be3d97c8e1f 100644 --- a/docs/src/catalyst-standards/draft-cips/role-registration/cip-xxxx.md +++ b/docs/src/catalyst-standards/draft-cips/role-registration/cip-xxxx.md @@ -84,7 +84,7 @@ Note: **7222 is RBAC when decoded using the telephone ITU E.161 standard** * UTF-8 strings **MUST** be valid UTF-8. * Tags **MUST NOT** be used unless specified in the specification. * Any Tags defined in the specification are **REQUIRED**, and they **MUST** be present in the encoded data. -* Fields which should be tagged, but which are not tagged will be considered invalid. + * Fields which should be tagged, but which are not tagged will be considered invalid. These validity checks apply only to the encoding and decoding of the metadata itself. There are other validity requirements based on the role registration data itself. @@ -129,7 +129,7 @@ Informally, all Registrations follow the same generalized Format (Non-Normative) 6: #6.37 h'a3c12b1c98af4ee8b54278e77906c0fc'; or // UUID #6.32770 h'018d1d2acaf04486be189dbc5ae35e51', // ULID // Expires - Optional - 7: 0, + 7: #6.1 0, // dApp Defined Metadata - Optional 100: } From 9766001e51657c1110a5febc42690570e84e0338 Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Fri, 19 Jan 2024 15:16:04 +0700 Subject: [PATCH 21/66] docs(cips): Add CBOR tag cip for ED25519-BIP32 Keys, Derivation paths and Signatures --- .../draft-cips/ed25519-cbor-tags/cip-xxxx.md | 174 ++++++++++++++++++ 1 file changed, 174 insertions(+) create mode 100644 docs/src/catalyst-standards/draft-cips/ed25519-cbor-tags/cip-xxxx.md diff --git a/docs/src/catalyst-standards/draft-cips/ed25519-cbor-tags/cip-xxxx.md b/docs/src/catalyst-standards/draft-cips/ed25519-cbor-tags/cip-xxxx.md new file mode 100644 index 00000000000..3be607106ec --- /dev/null +++ b/docs/src/catalyst-standards/draft-cips/ed25519-cbor-tags/cip-xxxx.md @@ -0,0 +1,174 @@ +--- +CIP: /? +Title: CBOR Tag definition for CIP-0003 ED25519-BIP32 Keys +Category: MetaData +Status: Proposed +Authors: + - Steven Johnson +Implementors: [] +Discussions: + - https://github.com/cardano-foundation/cips/pulls/? +Created: 2024-1-19 +License: CC-BY-4.0 +--- + + + + +# [CBOR] Tag definition for [CIP-0003] [ED25519-BIP32] Keys + +## Abstract + +[CIP-0003] defines [ED25519-BIP32] Keys, Key derivation and a signature scheme. + +These elements are commonly found in [CBOR] data structures within metadata on Cardano. +[CBOR] allows the definition of Tags to unambiguously define data structures encoded in [CBOR]. +IANA maintains the registry of these Tags as the [IANA CBOR Tag Registry]. +This CIP simply defines Tags to be registered with IANA and standardizes encoding of these data structures when the Tags are used. + +While use of these tags would be recommended, they would not be mandatory. + +## Motivation: why is this CIP necessary? + +Tags are a useful addition to [CBOR] encoding which allows encoded data to be unambiguously identified. +Judicious use of tags in [CDDL] Specs and [CBOR] encoding can ease forward compatibility. +The Tag on an encoded field can be used to identify what is contained in a particular field. + +For example, without this Tag definition, a metadata CIP which uses [ED25519-BIP32] public keys: + +1. Is likely to just encode public keys as a byte string of 32 bytes; and +2. Needs to redundantly define how the keys are encoded in the byte string. +3. Different metadata may encode these keys differently which can lead to confusion and potential error. + +However, [BIP32] defines secp256k1 keys and derivation, which are also 32 bytes long. +There is no standard compliant way for a metadata CIP currently to clearly define which particular key is being encoded. +While bespoke schemes could be utilized, it is generally better to utilize pre-existing industry standards. +Bespoke schemes are also likely to vary from Metadata CIP to metadata CIP causing a lack of uniformity and greater chance of error. +Using the Tags system built into [CBOR] allows for uniformity of specification and encoding. +Not using Tags makes Metadata CIPs either more complex or limits their flexibility and constrains forward compatibility. + +Bitcoin defines CBOR Tags at: [BCR-2020-006] + +## Specification + +| Type | [CBOR] Tag | IANA Registered | +| -- | -- | -- | +| [ED25519-BIP32 Private Key](#ed25519-bip32-private-key) | 32771 | :heavy_multiplication_x: | +| [ED25519-BIP32 Extended Private Key](#ed25519-bip32-extended-private-key) | 32772 | :heavy_multiplication_x: | +| [ED25519-BIP32 Public Key](#ed25519-bip32-public-key) | 32773 | :heavy_multiplication_x: | +| [ED25519-BIP32 Derivation Path](#ed25519-bip32-derivation-path) | 32774 | :heavy_multiplication_x: | +| [ED25519-BIP32 Private Key](#ed25519-bip32-signature) | 32775 | :heavy_multiplication_x: | + +### ED25519-BIP32 Private Key + +This key is defined in [ED25519-BIP32]. + +This is encoded as a byte string of size 32 bytes. + +#### CDDL + +```cddl +ed25519_private_key = #6.32771(bstr .size 32) +``` + +Data for the key inside the byte string is encoded in [network byte order]. + +### ED25519-BIP32 Extended Private Key + +This key is defined in [ED25519-BIP32]. + +This is encoded as a byte string of size 64 bytes. + +#### CDDL + +```cddl +ed25519_extended_private_key = #6.32772(bstr .size 64) +``` + +Data for the key inside the byte string is encoded in [network byte order]. + +### ED25519-BIP32 Public Key + +This key is defined in [ED25519-BIP32]. + +This is encoded as a byte string of size 32 bytes. + +#### CDDL + +```cddl +ed25519_public_key = #6.32773(bstr .size 32) +``` + +Data for the key inside the byte string is encoded in [network byte order]. + +### ED25519-BIP32 Derivation Path + +[ED25519-BIP32] defines that the derivation path is composed of 32 bit integers. +Where the most significant bit defines if the derivation is hardened or not. + +This is encoded as a CBOR Array, where each element is the component of the path. +There can be as many elements to the path as required. +Each element must be no larger than a 32 bit integer. + +For example the path `m / 1852' / 1815' / 0' / 23 / 45` would be encoded as: + +```cbor +[0x8000073c, 0x80000717, 0x80000000, 0x17, 0x2d] +``` + +#### CDDL + +```cddl +ed25519_derivation_path = #6.32774([* path_element]) +path_element = uint .le 0xffffffff +``` + +### ED25519-BIP32 Signature + +[ED25519-BIP32] defines how signatures can be generated from private keys. +These signatures are defined to be 64 bytes long. + +Signatures are encoded as a byte string of size 64 bytes. + +#### CDDL + +```cddl +ed25519_bip32_signature = #6.32775(bstr .size 64) +``` + +Data for the signature inside the byte string is encoded in [network byte order]. + +## Rationale: how does this CIP achieve its goals? + +By defining concrete CBOR tags, it is possible for metadata to unambiguously mark the kind of data encoded. +This is conformant with the intent of Tags in [CBOR], and aligns with prior use in [BCR-2020-006]. +An official published spec is required to register these Tags with IANA and so this document also serves that purpose. + +## Path to Active + +### Acceptance Criteria + +* At least 1 Metadata CIP uses at least 1 of the tags defined in this CIP. +* IANA register the Tags as defined. + +### Implementation Plan + +* Some of these Tags will be used by Project Catalyst in their new metadata CIPs. +* Project Catalyst will also make the application to IANA to register the Tags when appropriate. + +## Copyright + +This CIP is licensed under [CC-BY-4.0] + +Code samples and reference material are licensed under [Apache 2.0] + +[CC-BY-4.0]: https://creativecommons.org/licenses/by/4.0/legalcode +[Apache 2.0]: https://www.apache.org/licenses/LICENSE-2.0.html +[CBOR]: https://www.rfc-editor.org/rfc/rfc8949.html +[CDDL]: https://www.rfc-editor.org/rfc/rfc8610 +[CIP-0003]: https://cips.cardano.org/cip/CIP-0003 +[BIP32]: https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki +[BCR-2020-006]: https://github.com/BlockchainCommons/Research/blob/master/papers/bcr-2020-006-urtypes.md +[IANA CBOR Tag Registry]: https://www.iana.org/assignments/cbor-tags/cbor-tags.xhtml +[network byte order]: https://datatracker.ietf.org/doc/html/rfc1700 +[ED25519-BIP32]: https://github.com/input-output-hk/adrestia/raw/bdf00e4e7791d610d273d227be877bc6dd0dbcfb/user-guide/static/Ed25519_BIP.pdf From d0682f7bedcdbe7ff29fcb68039ef0fb65d3dc41 Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Fri, 19 Jan 2024 17:06:38 +0700 Subject: [PATCH 22/66] docs(cips): Properly define the field tags to use where known, and clean up Stake Address specification. --- .../draft-cips/role-registration/cip-xxxx.md | 38 ++++++++----------- 1 file changed, 16 insertions(+), 22 deletions(-) diff --git a/docs/src/catalyst-standards/draft-cips/role-registration/cip-xxxx.md b/docs/src/catalyst-standards/draft-cips/role-registration/cip-xxxx.md index be3d97c8e1f..d4e6135a6ad 100644 --- a/docs/src/catalyst-standards/draft-cips/role-registration/cip-xxxx.md +++ b/docs/src/catalyst-standards/draft-cips/role-registration/cip-xxxx.md @@ -95,7 +95,7 @@ Each dApp may have further validity requirements beyond those stated herein. At a high level, Role registration will collect the following data: 1. A [role public key or non-empty list of role public keys](#subkey-1---role-specific-public-key-or-role-public-key-array); -2. A [stake address for the network that this transaction is submitted to](); +2. A [stake address for the network that this transaction is submitted to](#subkey-2---stake-public-key); 3. An *Optional* [Shelley payment address](). 4. A [nonce]() that identifies that most recent registration. 5. The [role]() being registered. @@ -110,15 +110,15 @@ Informally, all Registrations follow the same generalized Format (Non-Normative) ```cbor 7222: { // Role Public Key or Role Public Key Array - 1: #6.??? h'a6a3c0447aeb9cc54cf6422ba32b294e5e1c3ef6d782f2acff4a70694c4d1663' ; or - [#6.??? h'A71A8700248D4C91E01A2A2CB5F4F0E664F084EB761C6792AEDD28160C1E403C', - #6.??? h'C606D983C5545800FAF20519D21988AA0A13271BA12BA9A8643FCFAD58697C97'] ; or + 1: #6.32773(h'a6a3c0447aeb9cc54cf6422ba32b294e5e1c3ef6d782f2acff4a70694c4d1663') ; or + [#6.32773(h'A71A8700248D4C91E01A2A2CB5F4F0E664F084EB761C6792AEDD28160C1E403C'), + #6.32773(h'C606D983C5545800FAF20519D21988AA0A13271BA12BA9A8643FCFAD58697C97')] ; or [ - [#6.??? h'A71A8700248D4C91E01A2A2CB5F4F0E664F084EB761C6792AEDD28160C1E403C', 50], - [#6.??? h'C606D983C5545800FAF20519D21988AA0A13271BA12BA9A8643FCFAD58697C97', 50] + [#6.32773(h'A71A8700248D4C91E01A2A2CB5F4F0E664F084EB761C6792AEDD28160C1E403C'), 50], + [#6.32773(h'C606D983C5545800FAF20519D21988AA0A13271BA12BA9A8643FCFAD58697C97'), 50] ] // Stake Public Key - 2: #6.??? h'ad4b948699193634a39dd56f779a2951a24779ad52aa7916f6912b8ec4702cee', + 2: #6.32773(h'ad4b948699193634a39dd56f779a2951a24779ad52aa7916f6912b8ec4702cee'), // Payment Address 3: #6.???h'00588e8e1d18cba576a4d35758069fe94e53f638b6faf7c07b8abd2bc5c5cdee47b60edc7772855324c85033c638364214cbfc6627889f81c4', // nonce @@ -129,9 +129,9 @@ Informally, all Registrations follow the same generalized Format (Non-Normative) 6: #6.37 h'a3c12b1c98af4ee8b54278e77906c0fc'; or // UUID #6.32770 h'018d1d2acaf04486be189dbc5ae35e51', // ULID // Expires - Optional - 7: #6.1 0, + 7: #6.1(0), // dApp Defined Metadata - Optional - 100: + 100+: } ``` @@ -333,31 +333,25 @@ Examples of acceptable `keyType`s for supporting tools: | `CIP36RoleSigningKey_ed25519` | CIPxx Role Signing Key | | `CIP36RoleVerificationKey_ed25519` | CIPxx Role Verification Key | -For hardware implementations: -| `keyType` | Description | -| --------- | ----------- | -| `CIP36RoleVerificationKey_ed25519` | Hardware CIPxx Role Verification Key | -| `CIP36RoleHWSigningFile_ed25519` | Hardware CIPxx Role Signing File | - ### SubKey 2 - Stake Public Key This is represented as a CBOR Byte-string, 32 bytes long. -This is the actual ed25519 Stake Public key of the wallet, and NOT the stake key public hash. -This is the primary key [ - [h'A71A8700248D4C91E01A2A2CB5F4F0E664F084EB761C6792AEDD28160C1E403C', 25], - [h'C606D983C5545800FAF20519D21988AA0A13271BA12BA9A8643FCFAD58697C97', 75] -]associating the users wallet with their role key. +This is the actual [ED25519-BIP32] Stake Public key of the wallet, and NOT the stake key public hash. +This is the primary key associating the users wallet with their role key. How the dApp uses this information is dApp specific. -For example Project Catalyst uses this information to derive voting power for a voter role. +For example Project Catalyst can use this information to derive voting power for a voter role. It is an ed25519 public key, and is represented as a byte-string 32 bytes in length. Example: ```cbor -h'ad4b948699193634a39dd56f779a2951a24779ad52aa7916f6912b8ec4702cee' +#6.32773(h'ad4b948699193634a39dd56f779a2951a24779ad52aa7916f6912b8ec4702cee') ``` +Note: There can only be a single Stake Public Key in the registration. +Multiple Stake Public Keys can be associated with the same Role Key/s, however there needs to be one registration per stake address. + ### SubKey 3 - Payment Address (OPTIONAL) This is represented as a CBOR Byte-string, Between 29 and 57 bytes long (inclusive). From 7b6eda3415f26c250627b3efe20b2ca8dc875f37 Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Fri, 26 Jan 2024 20:07:13 +0700 Subject: [PATCH 23/66] docs(cips): Fix nonce so its reliable without needing blockchain data --- .../catalyst-standards/draft-cips/role-registration/cip-xxxx.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/catalyst-standards/draft-cips/role-registration/cip-xxxx.md b/docs/src/catalyst-standards/draft-cips/role-registration/cip-xxxx.md index d4e6135a6ad..9a0a6c61adf 100644 --- a/docs/src/catalyst-standards/draft-cips/role-registration/cip-xxxx.md +++ b/docs/src/catalyst-standards/draft-cips/role-registration/cip-xxxx.md @@ -122,7 +122,7 @@ Informally, all Registrations follow the same generalized Format (Non-Normative) // Payment Address 3: #6.???h'00588e8e1d18cba576a4d35758069fe94e53f638b6faf7c07b8abd2bc5c5cdee47b60edc7772855324c85033c638364214cbfc6627889f81c4', // nonce - 4: 5479467, + 4: #6.32770 h'018d45d8deb3a1b171f6b38577ecee20', // ULID // Role 5: 0, // dApp ID (UUID or ULID) From d95dc251c4aa935af914dcc07f348b6f13fe73cd Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Fri, 8 Mar 2024 17:42:26 +0700 Subject: [PATCH 24/66] docs(cips): updates --- .../draft-cips/role-registration/cip-xxxx.md | 53 +++++++++++++++++-- 1 file changed, 49 insertions(+), 4 deletions(-) diff --git a/docs/src/catalyst-standards/draft-cips/role-registration/cip-xxxx.md b/docs/src/catalyst-standards/draft-cips/role-registration/cip-xxxx.md index 9a0a6c61adf..b33f48b41ac 100644 --- a/docs/src/catalyst-standards/draft-cips/role-registration/cip-xxxx.md +++ b/docs/src/catalyst-standards/draft-cips/role-registration/cip-xxxx.md @@ -12,13 +12,11 @@ Created: 2023-10-24 License: CC-BY-4.0 / Apache 2.0 --- - -# Role Based Access Control Registration - ## Abstract dApps such as Project Catalyst need robust, secure and extensible means for users to register under various roles -and for the dApp to be able to validate actions against those roles. +and for the dApp to be able to validate actions against those roles with its users. + While these Role based registrations are required for future functionality of Project Catalyst, they are also intended to be generally useful to any dApp with User roles. @@ -60,6 +58,52 @@ motivated to solve problems with Project Catalyst, it is also intended to be gen ## Specification +In order to maintain a robust set of role registration capabilities Role registration involves: + +1. Creation of a root certificate for a user or set of users and associating it with an on-chain source of trust. +2. Obtaining for each user of a dapp, or a set of users, their root +3. Deriving role specific keys from the root certificate. +4. Optionally registering for those roles on-chain. +5. Signing and/or encrypting data with the root certificate or a derived key, or a certificate issued by a previously registered root certificate. + +Effectively we map the blockchain as PKI (Public Key Infrastructure) and define the methods a dapp can use to exploit this PKI. + +### Mapping the PKI to Cardano + +A PKI consists of: + +* A certificate authority (CA) that stores, issues and signs the digital certificates; + * Each dApp can control its own CA, the user trusts the dApp as CA implicitly (or explicitly) by using the dApp. + * It is permissible for root certificates to be self signed, effectively each user becomes their own CA. + * However all Certificates are associated with blockchain addresses, typically the Stake address, but also potentially the drep key. +* A registration authority (RA) which verifies the identity of entities requesting their digital certificates to be stored at the CA; + * Each dApp is responsible for identifying certificates relevant for its use that are stored on-chain and are their own RA. +* A central directory—i.e., a secure location in which keys are stored and indexed; + * This is the blockchain itself. +* A certificate management system managing things like the access to stored certificates or the delivery of the certificates to be issued; + * This is managed by each dApp in the manor required of the dApp. +* A certificate policy stating the PKI's requirements concerning its procedures. + Its purpose is to allow outsiders to analyze the PKI's trustworthiness. + * This is also defined and managed by each dApp. + +### The role x.509 plays in this scheme + +We leverage the x.509 PKI primitives and take advantage of the significant existing code bases and infrastructure which already exists. + +We encode x.509 certificates using [CBOR Encoded X.509 Certificates][C509], Each certificate includes its on-chain anchor (public key). +The on-chain anchors currently envisioned are: + +1. Stake Address +2. dRep Key + +The transaction that is submitted on-chain which includes the certificate in its metadata MUST be witnessed by it's on-chain anchor. +This is used to prove that the certificate and on-chain anchor are controlled by the same entity. +It prevents replay attacks where people could try and associate a different on-chain anchor with a certificate. + +--- + +Note: **The information below is to be reviewed in-light of the above** + Role registration is achieved by using two metadata records attached to the same transaction. ### Metadata Labels @@ -530,3 +574,4 @@ Code samples and reference material are licensed under [Apache 2.0] [CBOR]: https://www.rfc-editor.org/rfc/rfc8949.html [CBOR - Core Deterministic Encoding Requirements]: https://www.rfc-editor.org/rfc/rfc8949.html#section-4.2.1 [CIP0003]: https://cips.cardano.org/cip/CIP-0003 +[C509]: https://datatracker.ietf.org/doc/html/draft-ietf-cose-cbor-encoded-cert-07 From 8e7e579642ec66d346f4c8fb4d90d42323b146db Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Wed, 13 Mar 2024 15:48:59 +0700 Subject: [PATCH 25/66] docs(docs): Add CDDL definition for POC x509 envelope metadata --- .../role-registration/x509-envelope.cddl | 51 +++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 docs/src/catalyst-standards/draft-cips/role-registration/x509-envelope.cddl diff --git a/docs/src/catalyst-standards/draft-cips/role-registration/x509-envelope.cddl b/docs/src/catalyst-standards/draft-cips/role-registration/x509-envelope.cddl new file mode 100644 index 00000000000..cc3f5789449 --- /dev/null +++ b/docs/src/catalyst-standards/draft-cips/role-registration/x509-envelope.cddl @@ -0,0 +1,51 @@ +; An envelope for cardano metadata which holds the x509 metadata. +; We do thsi so that the underlying metadata is not restircted to +; cardano ledger implementation. + +; uses +x509_envelope = { + 0: purpose, ; What purpose does this metadata serve. + 1: required_signers_hash, ; A hash of the `required_signers` field from the transaction the metadata is posted with. + chunk_type: [ + x509_chunk ] + 99: [ + validation_signature ] ; The signature/s of the x509 certificate metadata record. +} + +; Chunk Types - Allows to identify how the chunk data is compressed to save on-chain space. +; 2 : Chunk data is encoded raw +; 3 : Data is compressed with Brotli and then chunked. +; 4 : Data is compressed with ZSTD and then chunked. +chunk_type = ( 2 4 ) + +; An individual purpose or set or purposes +purpose = ( individual_purpose [ * individual_purpose ] ) + +; A V4 UUID encoded as per https://datatracker.ietf.org/doc/html/rfc4122#section-4.1.2 +individual_purpose = (bytes .size (16)) + +; Transaction Required Signers Hash - Blake2b-224 +required_signers_hash = (bytes .size (28)) + +; A single x509 chunk +x509_chunk = (bytes .size (0..64)) + +; A Validation Signature +validation_signature = (bytes .size (0..64)) + +; Signatures are created by creating the x509_envelope with key `99`, but without all expected signatures set to 0x00's. +; Each signature is then computed over that binary data. +; Each blank signature is then replaced with the real signature. + +; To validate the opposite occurs, the signatures are copied out of the envelope. +; The signature fields are set to 0x00's +; The resulting binary buffer is then checked against the signatures which were embedded. + +; Explanation: +; The purpose of the Envelope is to ensure that metadata is not transportable between +; transactions. +; +; Transactions contain a `required_signers` field. +; By including a hash of that field within the metatdata, we can validated the transaction it was intended for. +; By signing the metadata envelope with the keys contained within the x509 chunks, we ensure that its not possible +; to transpose key certs from one transaction to another. + +; This envelope is general in structure, and that structure ensures metadata can not be transposed or tampoered with outside of the inteheg \ No newline at end of file From 153170e1abb1bd456e77824895df77e6bdeacc7e Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Wed, 13 Mar 2024 15:49:40 +0700 Subject: [PATCH 26/66] fix(vscode): update vscode extension recommendations --- .vscode/extensions.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.vscode/extensions.json b/.vscode/extensions.json index f0db3264852..1b62d9eb882 100644 --- a/.vscode/extensions.json +++ b/.vscode/extensions.json @@ -15,6 +15,6 @@ "rust-lang.rust-analyzer", "JScearcy.rust-doc-viewer", "serayuzgur.crates", - "panicbit.cargo", + "anweiss.cddl-languageserver", ] } \ No newline at end of file From c665fd751a00f46f804414fcc01f84e7856bc3f0 Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Wed, 13 Mar 2024 21:11:28 +0700 Subject: [PATCH 27/66] docs(cips): rbac x509 envelope fix --- .../draft-cips/role-registration/x509-envelope.cddl | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/src/catalyst-standards/draft-cips/role-registration/x509-envelope.cddl b/docs/src/catalyst-standards/draft-cips/role-registration/x509-envelope.cddl index cc3f5789449..9ab31785bce 100644 --- a/docs/src/catalyst-standards/draft-cips/role-registration/x509-envelope.cddl +++ b/docs/src/catalyst-standards/draft-cips/role-registration/x509-envelope.cddl @@ -14,7 +14,7 @@ x509_envelope = { ; 2 : Chunk data is encoded raw ; 3 : Data is compressed with Brotli and then chunked. ; 4 : Data is compressed with ZSTD and then chunked. -chunk_type = ( 2 4 ) +chunk_type = ( 2..4 ) ; An individual purpose or set or purposes purpose = ( individual_purpose [ * individual_purpose ] ) @@ -34,7 +34,7 @@ validation_signature = (bytes .size (0..64)) ; Signatures are created by creating the x509_envelope with key `99`, but without all expected signatures set to 0x00's. ; Each signature is then computed over that binary data. ; Each blank signature is then replaced with the real signature. - +.. ; To validate the opposite occurs, the signatures are copied out of the envelope. ; The signature fields are set to 0x00's ; The resulting binary buffer is then checked against the signatures which were embedded. @@ -48,4 +48,4 @@ validation_signature = (bytes .size (0..64)) ; By signing the metadata envelope with the keys contained within the x509 chunks, we ensure that its not possible ; to transpose key certs from one transaction to another. -; This envelope is general in structure, and that structure ensures metadata can not be transposed or tampoered with outside of the inteheg \ No newline at end of file +; This envelope is general in structure, and that structure ensures metadata can not be transposed or tampoered with outside of the inteheg From 0960b2fd7738fa18777620f80efabe270f294d59 Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Fri, 15 Mar 2024 13:34:45 +0700 Subject: [PATCH 28/66] docs(cips): wip updates to high level docs --- .../draft-cips/role-registration/cip-xxxx.md | 51 +++++++++++++++---- 1 file changed, 42 insertions(+), 9 deletions(-) diff --git a/docs/src/catalyst-standards/draft-cips/role-registration/cip-xxxx.md b/docs/src/catalyst-standards/draft-cips/role-registration/cip-xxxx.md index b33f48b41ac..c7ea4567977 100644 --- a/docs/src/catalyst-standards/draft-cips/role-registration/cip-xxxx.md +++ b/docs/src/catalyst-standards/draft-cips/role-registration/cip-xxxx.md @@ -56,12 +56,29 @@ These are some of the key reasons, CIP-36 is insufficient for future Project Cat Registering for various roles and having role specific keys is generally useful for dApps, so while this CIP is motivated to solve problems with Project Catalyst, it is also intended to be generally applicable to other dApps. +There are a number of interactions with a user in a dApp like Catalyst which require authentication. +However forcing all authentication through a wallet has several primary disadvantages. + +* Wallets only are guaranteed to provide `signData` if they implement CIP30, and that only allows a single signature. +* There are multiple keys controlled by a wallet and its useful to ensure that all keys reflected are valid. +* Metadata in a transaction is inaccessible to plutus scripts. +* Wallets could present raw data to be signed to the user, and that makes the UX poor because the user would have difficulty + knowing what they are signing. +* Wallets could be extended to recognize certain metadata and provide better UX but that shifts dApp UX to every wallet. +* Putting chain keys in metadata can be redundant if those keys are already in the transaction. +* Some authentication needs to change with regularity, such as authentication tokens to a backend service, + and this would require potentially excessive wallet interactions. + +The proposal here is to register dApp specific keys and identity, but strongly associate it with on-chain identity, +such as Stake Public Keys, Payment Keys and Drep Keys, such that off chain interactions can be fully authenticated, +and only on-chain interaction requires interaction with a Wallet. + ## Specification In order to maintain a robust set of role registration capabilities Role registration involves: 1. Creation of a root certificate for a user or set of users and associating it with an on-chain source of trust. -2. Obtaining for each user of a dapp, or a set of users, their root +2. Obtaining for each user of a dapp, or a set of users, their root certificate. 3. Deriving role specific keys from the root certificate. 4. Optionally registering for those roles on-chain. 5. Signing and/or encrypting data with the root certificate or a derived key, or a certificate issued by a previously registered root certificate. @@ -73,22 +90,38 @@ Effectively we map the blockchain as PKI (Public Key Infrastructure) and define A PKI consists of: * A certificate authority (CA) that stores, issues and signs the digital certificates; - * Each dApp can control its own CA, the user trusts the dApp as CA implicitly (or explicitly) by using the dApp. - * It is permissible for root certificates to be self signed, effectively each user becomes their own CA. - * However all Certificates are associated with blockchain addresses, typically the Stake address, but also potentially the drep key. -* A registration authority (RA) which verifies the identity of entities requesting their digital certificates to be stored at the CA; + * Each dApp *MAY* control its own CA, the user trusts the dApp as CA implicitly (or explicitly) by using the dApp. + * It is also permissible for root certificates to be self signed, effectively each user becomes their own CA. + * However all Certificates are associated with blockchain addresses, typically one or more Stake Public Key. + * A certificate could be associated with multiple Stake Addresses, Payment Addresses or DRep Public Keys, as required. + * A dApp may require that a well known public CA is used. + The chain of trust can extend off chain to centralized CAs. + * DAOs or other organizations can also act as a CA for their members. + * This is intentionally left open so that the requirements of the dApp can be flexibly accommodated. +* A registration authority (RA) which verifies the identity of entities requesting their digital certificates + to be stored at the CA; * Each dApp is responsible for identifying certificates relevant for its use that are stored on-chain and are their own RA. + * The dApp may choose to not do any identifying. + * The dApp can rely on decentralized identity to verify identity in a trustless way. * A central directory—i.e., a secure location in which keys are stored and indexed; * This is the blockchain itself. -* A certificate management system managing things like the access to stored certificates or the delivery of the certificates to be issued; - * This is managed by each dApp in the manor required of the dApp. + * As mentioned above, the chain of trust can extend off-chain to traditional Web2 CA's. +* A certificate management system managing things like the access to stored certificates or the delivery of the + certificates to be issued; + * This is managed by each dApp according to its requirements. * A certificate policy stating the PKI's requirements concerning its procedures. Its purpose is to allow outsiders to analyze the PKI's trustworthiness. - * This is also defined and managed by each dApp. + * This is also defined and managed by each dApp according to its requirements. ### The role x.509 plays in this scheme -We leverage the x.509 PKI primitives and take advantage of the significant existing code bases and infrastructure which already exists. +We leverage the x.509 PKI primitives. +We intentionally take advantage of the significant existing code bases and infrastructure which already exists. + +#### Certificate formats + +x.509 certificates can be encoded in + We encode x.509 certificates using [CBOR Encoded X.509 Certificates][C509], Each certificate includes its on-chain anchor (public key). The on-chain anchors currently envisioned are: From 322fbbc0043a61bdbb9fb921ccf2f987a4489c62 Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Fri, 15 Mar 2024 13:35:18 +0700 Subject: [PATCH 29/66] docs(cips): Add overview of cardano transaction processign and data --- .../role-registration/cardano-transaction.d2 | 150 ++++++++++++++++++ 1 file changed, 150 insertions(+) create mode 100644 docs/src/catalyst-standards/draft-cips/role-registration/cardano-transaction.d2 diff --git a/docs/src/catalyst-standards/draft-cips/role-registration/cardano-transaction.d2 b/docs/src/catalyst-standards/draft-cips/role-registration/cardano-transaction.d2 new file mode 100644 index 00000000000..20357e6a4c7 --- /dev/null +++ b/docs/src/catalyst-standards/draft-cips/role-registration/cardano-transaction.d2 @@ -0,0 +1,150 @@ +vars: { + d2-config: { + layout-engine: tala + + # Terminal theme code + + theme-id: 300 + } +} + +direction: right +grid-columns: 1 + +title: |md + # Cardano Transactions +| { + shape: text + # near: top-left + style: { + font-size: 30 + } +} + +processing: "Block to Individual Transaction Processing" { + direction: right + + style: { + border-radius: 20 + } + + cardano block transactions: { + shape: sql_table + link: "https://github.com/IntersectMBO/cardano-ledger/blob/6d860294304749a767d99db92fab42f7c18d9af4/eras/babbage/impl/cddl-files/babbage.cddl#L3-L6" + transaction bodies: "[ * transaction_body ]" + transaction witness sets: "[ *transaction_witness_set ]" + invalid transactions: "[* transaction_index ]" + auxiliary data set: "{ *transaction_index => auxiliary_data }" + } + + individual_transaction: { + shape: sql_table + link: "https://github.com/IntersectMBO/cardano-ledger/blob/6d860294304749a767d99db92fab42f7c18d9af4/eras/babbage/impl/cddl-files/babbage.cddl#L13-L18" + body: "transaction body" + witnesses: "transaction witness set" + valid: "bool" + auxiliary_data: "Option" + } + + collator: "collation logic: for i in 0..len(transaction_bodies)" { + shape: sql_table + style: { + stroke: PapayaWhip + font-color: cyan + } + 1: "transaction_bodies[i]" { + shape: text + style: { + font: mono + } + } + 2: "transaction_witness_sets[i]" { + shape: text + style: { + font: mono + } + } + 3: "i not in invalid_transactions" { + shape: text + style: { + font: mono + } + } + 4: "auxiliary_data_set[i] else None" { + shape: text + style: { + font: mono + } + } + } + + cardano block transactions.transaction bodies -> collator.1 + cardano block transactions.transaction witness sets -> collator.2 + cardano block transactions.auxiliary data set -> collator.4 + cardano block transactions.invalid transactions -> collator.3 + + collator.1 -> individual_transaction.body + collator.2 -> individual_transaction.witnesses + collator.3 -> individual_transaction.valid + collator.4 -> individual_transaction.auxiliary_data +} + +transaction_data: "Transaction Data Details" { + shape: page + + transaction_body: "transaction body" { + shape: sql_table + link: "https://github.com/IntersectMBO/cardano-ledger/blob/6d860294304749a767d99db92fab42f7c18d9af4/eras/babbage/impl/cddl-files/babbage.cddl#L53-L71" + "0 = transaction inputs": "[ * [transaction hash, index] ]" + "1 = transaction outputs": "[ * transaction_output ]" + "2 = transaction fee": "coin (lovelace uint64)" + "? 3 = Time to live \[TTL\]": "uint64" + "? 4 = certificates": "[* certificate]" + "? 5 = reward withdrawals": "{ * reward_account => coin (lovelace uint64) }" + "? 6 = protocol parameter update": "[ proposed_protocol_parameter_updates, epoch ]" + "? 7 = auxiliary_data_hash": "32 byte hash" + "? 8 = validity interval start": "uint64" + "? 9 = mint": "{ * policy_id => { * asset_name => a } }" + "? 11 = script_data_hash": "32 byte hash" + "? 13 = collateral inputs": "[ * [transaction hash, index] ]" + "? 14 = required_signers": "[ * address key hash (blake2b-224) of signing public key ]" + "? 15 = network_id": "0 or 1" + "? 16 = collateral return": transaction_output (collateral return) + "? 17 = total collateral": "coin (lovelace uint64)" + "? 18 = reference inputs": set + } + + transaction_witness_set: "transaction witness set" { + shape: sql_table + link: "https://github.com/IntersectMBO/cardano-ledger/blob/6d860294304749a767d99db92fab42f7c18d9af4/eras/babbage/impl/cddl-files/babbage.cddl#L295C1-L303" + "? 0": "[* vkeywitness ]" + "? 1": "[* native_script]" + "? 2": "[* bootstrap_witness]" + "? 3": "[* plutus_v1_script]" + "? 4": "[* plutus_data]" + "? 5": "[* redeemer]" + "? 6": "[* plutus_v2_script]" + } + + vkeywitness: { + shape: sql_table + link: "https://github.com/IntersectMBO/cardano-ledger/blob/6d860294304749a767d99db92fab42f7c18d9af4/eras/babbage/impl/cddl-files/babbage.cddl#L370" + "vkey": "ED25519-Bip32 Public Key [32 Bytes]" + "signature": "ED25519-Bip32 Signature of Transaction [64 bytes]" + } + + transaction_witness_set."? 0" -> vkeywitness + + auxiliary_data: "auxiliary data" { + shape: sql_table + link: "https://github.com/IntersectMBO/cardano-ledger/blob/6d860294304749a767d99db92fab42f7c18d9af4/eras/babbage/impl/cddl-files/babbage.cddl#L359C1-L368" + "{ * uint => transaction_metadatum }": Optional + "[ * native_script ]": Optional + "[ * plutus_v1_script ]": Optional + "[ * plutus_v2_script ]": Optional + } +} + +processing.individual_transaction.body -> transaction_data.transaction_body: "body" +processing.individual_transaction.witnesses -> transaction_data.transaction_witness_set: "witnesses" +processing.individual_transaction.auxiliary_data -> transaction_data.auxiliary_data: "auxiliary_data (optional)" From 2d9d8a9e1320eb48136320aaf8c35ee61ac92cc3 Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Fri, 15 Mar 2024 13:56:49 +0700 Subject: [PATCH 30/66] docs(cips): update cardano block to be complete for clarity --- .../draft-cips/role-registration/cardano-transaction.d2 | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/src/catalyst-standards/draft-cips/role-registration/cardano-transaction.d2 b/docs/src/catalyst-standards/draft-cips/role-registration/cardano-transaction.d2 index 20357e6a4c7..cefe84a6fe1 100644 --- a/docs/src/catalyst-standards/draft-cips/role-registration/cardano-transaction.d2 +++ b/docs/src/catalyst-standards/draft-cips/role-registration/cardano-transaction.d2 @@ -12,7 +12,7 @@ direction: right grid-columns: 1 title: |md - # Cardano Transactions + # Cardano Transactions - Babbage ERA | { shape: text # near: top-left @@ -28,16 +28,17 @@ processing: "Block to Individual Transaction Processing" { border-radius: 20 } - cardano block transactions: { + cardano block transactions: "Cardano Block (Babbage ERA)" { shape: sql_table link: "https://github.com/IntersectMBO/cardano-ledger/blob/6d860294304749a767d99db92fab42f7c18d9af4/eras/babbage/impl/cddl-files/babbage.cddl#L3-L6" + header: "[ header_body, body_signature ]" transaction bodies: "[ * transaction_body ]" transaction witness sets: "[ *transaction_witness_set ]" invalid transactions: "[* transaction_index ]" auxiliary data set: "{ *transaction_index => auxiliary_data }" } - individual_transaction: { + individual_transaction: "Cardano Transaction" { shape: sql_table link: "https://github.com/IntersectMBO/cardano-ledger/blob/6d860294304749a767d99db92fab42f7c18d9af4/eras/babbage/impl/cddl-files/babbage.cddl#L13-L18" body: "transaction body" From 7fd0c00febbe27c6ca22c6d64c1e125ab9ceebd7 Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Fri, 15 Mar 2024 14:22:37 +0700 Subject: [PATCH 31/66] docs(cips): fix layout engine --- .../draft-cips/role-registration/cardano-transaction.d2 | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/src/catalyst-standards/draft-cips/role-registration/cardano-transaction.d2 b/docs/src/catalyst-standards/draft-cips/role-registration/cardano-transaction.d2 index cefe84a6fe1..788ca10fab5 100644 --- a/docs/src/catalyst-standards/draft-cips/role-registration/cardano-transaction.d2 +++ b/docs/src/catalyst-standards/draft-cips/role-registration/cardano-transaction.d2 @@ -1,9 +1,8 @@ vars: { d2-config: { - layout-engine: tala + layout-engine: elk # Terminal theme code - theme-id: 300 } } From e0cb03cce821fe17aca66e4ca0475ec21b78fde8 Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Wed, 20 Mar 2024 11:05:06 +0700 Subject: [PATCH 32/66] docs(cips): wip cddl for envelope metadata --- .../draft-cips/role-registration/x509-envelope.cddl | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/src/catalyst-standards/draft-cips/role-registration/x509-envelope.cddl b/docs/src/catalyst-standards/draft-cips/role-registration/x509-envelope.cddl index 9ab31785bce..6e1af83cb56 100644 --- a/docs/src/catalyst-standards/draft-cips/role-registration/x509-envelope.cddl +++ b/docs/src/catalyst-standards/draft-cips/role-registration/x509-envelope.cddl @@ -14,7 +14,7 @@ x509_envelope = { ; 2 : Chunk data is encoded raw ; 3 : Data is compressed with Brotli and then chunked. ; 4 : Data is compressed with ZSTD and then chunked. -chunk_type = ( 2..4 ) +chunk_type = (2..4) ; An individual purpose or set or purposes purpose = ( individual_purpose [ * individual_purpose ] ) @@ -34,7 +34,7 @@ validation_signature = (bytes .size (0..64)) ; Signatures are created by creating the x509_envelope with key `99`, but without all expected signatures set to 0x00's. ; Each signature is then computed over that binary data. ; Each blank signature is then replaced with the real signature. -.. + ; To validate the opposite occurs, the signatures are copied out of the envelope. ; The signature fields are set to 0x00's ; The resulting binary buffer is then checked against the signatures which were embedded. @@ -48,4 +48,5 @@ validation_signature = (bytes .size (0..64)) ; By signing the metadata envelope with the keys contained within the x509 chunks, we ensure that its not possible ; to transpose key certs from one transaction to another. -; This envelope is general in structure, and that structure ensures metadata can not be transposed or tampoered with outside of the inteheg +; This envelope is general in structure, and that structure ensures metadata can not be transposed between transactions + From 3e35923889f7de8cb320b717cf3d7e7c51532d05 Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Fri, 22 Mar 2024 21:07:57 +0700 Subject: [PATCH 33/66] docs(cips): Add cddl specs and diagrams for x509 rbac registration work --- .../role-registration/cardano-transaction.svg | 923 ++++++++++++++++++ .../role-registration/certificate-chain.d2 | 110 +++ .../role-registration/certificate-chain.svg | 870 +++++++++++++++++ .../role-registration/metadata-envelope.d2 | 138 +++ .../role-registration/metadata-envelope.svg | 875 +++++++++++++++++ .../role-registration/x509-envelope.cddl | 97 +- .../role-registration/x509-roles.cddl | 123 +++ .../role-registration/x509-roles.d2 | 44 + .../role-registration/x509-roles.svg | 836 ++++++++++++++++ 9 files changed, 3982 insertions(+), 34 deletions(-) create mode 100644 docs/src/catalyst-standards/draft-cips/role-registration/cardano-transaction.svg create mode 100644 docs/src/catalyst-standards/draft-cips/role-registration/certificate-chain.d2 create mode 100644 docs/src/catalyst-standards/draft-cips/role-registration/certificate-chain.svg create mode 100644 docs/src/catalyst-standards/draft-cips/role-registration/metadata-envelope.d2 create mode 100644 docs/src/catalyst-standards/draft-cips/role-registration/metadata-envelope.svg create mode 100644 docs/src/catalyst-standards/draft-cips/role-registration/x509-roles.cddl create mode 100644 docs/src/catalyst-standards/draft-cips/role-registration/x509-roles.d2 create mode 100644 docs/src/catalyst-standards/draft-cips/role-registration/x509-roles.svg diff --git a/docs/src/catalyst-standards/draft-cips/role-registration/cardano-transaction.svg b/docs/src/catalyst-standards/draft-cips/role-registration/cardano-transaction.svg new file mode 100644 index 00000000000..3dcd2a8c4fb --- /dev/null +++ b/docs/src/catalyst-standards/draft-cips/role-registration/cardano-transaction.svg @@ -0,0 +1,923 @@ +

Cardano Transactions - Babbage ERA

+
Block to Individual Transaction ProcessingTransaction Data DetailsCardano Block (Babbage ERA)header[ header_body, body_signature ]transaction bodies[ * transaction_body ]transaction witness sets[ *transaction_witness_set ]invalid transactions[* transaction_index ]auxiliary data set{ *transaction_index => auxiliary_data }Cardano Transactionbodytransaction bodywitnessestransaction witness setvalidboolauxiliary_dataOption<auxiliary_data>collation logic: for i in 0..len(transaction_bodies)1transaction_bodies[i]2transaction_witness_sets[i]3i not in invalid_transactions4auxiliary_data_set[i] else Nonetransaction body0 = transaction inputs[ * [transaction hash, index] ]1 = transaction outputs[ * transaction_output ]2 = transaction feecoin (lovelace uint64)? 3 = Time to live [TTL]uint64? 4 = certificates[* certificate]? 5 = reward withdrawals{ * reward_account => coin (lovelace uint64) }? 6 = protocol parameter update[ proposed_protocol_parameter_updates, epoch ]? 7 = auxiliary_data_hash32 byte hash? 8 = validity interval startuint64? 9 = mint{ * policy_id => { * asset_name => a } }? 11 = script_data_hash32 byte hash? 13 = collateral inputs[ * [transaction hash, index] ]? 14 = required_signers[ * address key hash (blake2b-224) of signing public key ]? 15 = network_id0 or 1? 16 = collateral returntransaction_output (collateral return)? 17 = total collateralcoin (lovelace uint64)? 18 = reference inputsset<transaction_input>transaction witness set? 0[* vkeywitness ]? 1[* native_script]? 2[* bootstrap_witness]? 3[* plutus_v1_script]? 4[* plutus_data]? 5[* redeemer]? 6[* plutus_v2_script]vkeywitnessvkeyED25519-Bip32 Public Key [32 Bytes]signatureED25519-Bip32 Signature of Transaction [64 bytes]auxiliary data{ * uint => transaction_metadatum }Optional[ * native_script ]Optional[ * plutus_v1_script ]Optional[ * plutus_v2_script ]Optional bodywitnessesauxiliary_data (optional) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/src/catalyst-standards/draft-cips/role-registration/certificate-chain.d2 b/docs/src/catalyst-standards/draft-cips/role-registration/certificate-chain.d2 new file mode 100644 index 00000000000..df7b931d270 --- /dev/null +++ b/docs/src/catalyst-standards/draft-cips/role-registration/certificate-chain.d2 @@ -0,0 +1,110 @@ +vars: { + d2-config: { + layout-engine: elk + + # Terminal theme code + theme-id: 300 + } +} + +classes: { + NONE: {style.opacity: 0} + PRIVATE_KEY: { + shape: sql_table + style: { + border-radius: 15 + stroke: wheat + fill: cornsilk + font-color: red + } + } + SIGN: { + style: { + stroke-dash: 3 + stroke: blueviolet + animated: true + } + } +} + +title: |md + # Chaining Certificates +| { + # shape: text + near: top-center + # style: { + # font-size: 8 + # } +} + +root-ca: "ROOT CERTIFICATE AUTHORITY (CA)" { + # shape: text + + pad.class: NONE + + key: "Root CA's Key Pair" { + class: PRIVATE_KEY + private: Secret + public: Shared + } + + certificate: "Root Certificate (ROOT CA)" { + shape: sql_table + "Subject`s Name": "ROOT CA Name" + "Subject`s PublicKey": Public Key + "Issuer`s Name": "ROOT CA Name" + "Issuer`s Signature": Signature + "Subject Alt. Name": "URI:S:ada:stake1vpu...p0u" + } + + key.public -> certificate."Subject`s PublicKey": Published + key.private -> certificate."Issuer`s Signature": Self Sign {class: SIGN} +} + +intermediate-ca: "INTERMEDIATE CERTIFICATE AUTHORITY (CA)" { + key: "Intermediate CA's Key Pair" { + class: PRIVATE_KEY + private: Secret + public: Shared + } + + certificate: "Intermediate Certificate (Intermediate CA)" { + shape: sql_table + "Subject`s Name": "Intermediate CA Name" + "Subject`s PublicKey": Public Key + "Issuer`s Name": "Root CA Name" + "Issuer`s Signature": Signature + "Subject Alt. Name": "URI:S:ada:stake1ngf...8dy" + "": "URI:S:ada:cc_cold16cj..80v" + } + + key.public -> certificate."Subject`s PublicKey": Published +} + +root-ca.key.private -> intermediate-ca.certificate."Issuer`s Signature": Sign {class: SIGN} +root-ca.certificate."Subject`s Name" <- intermediate-ca.certificate."Issuer`s Name": References +root-ca.certificate <- intermediate-ca.certificate: Verifies + +entity-cert: "End-Entity Certificate" { + key: "Entities Key Pair" { + class: PRIVATE_KEY + private: Secret + public: Shared + } + + certificate: "Intermediate Certificate (Intermediate CA)" { + shape: sql_table + "Subject`s Name": "Entities Name" + "Subject`s PublicKey": Public Key + "Issuer`s Name": "Intermediate CA Name" + "Issuer`s Signature": Signature + "Subject Alt. Name": "URI:S:ada:stake1ngf...v2q" + "": "URI:S:ada:drep1ayt..80v" + } + + key.public -> certificate."Subject`s PublicKey": Published +} + +intermediate-ca.certificate <- entity-cert.certificate: Verifies +intermediate-ca.key.private -> entity-cert.certificate."Issuer`s Signature": Sign {class: SIGN} +intermediate-ca.certificate."Subject`s Name" <- entity-cert.certificate."Issuer`s Name": References diff --git a/docs/src/catalyst-standards/draft-cips/role-registration/certificate-chain.svg b/docs/src/catalyst-standards/draft-cips/role-registration/certificate-chain.svg new file mode 100644 index 00000000000..eb326806351 --- /dev/null +++ b/docs/src/catalyst-standards/draft-cips/role-registration/certificate-chain.svg @@ -0,0 +1,870 @@ +

Chaining Certificates

+
ROOT CERTIFICATE AUTHORITY (CA)INTERMEDIATE CERTIFICATE AUTHORITY (CA)End-Entity Certificatepad Root CA's Key PairprivateSecretpublicSharedRoot Certificate (ROOT CA)Subject`s NameROOT CA NameSubject`s PublicKeyPublic KeyIssuer`s NameROOT CA NameIssuer`s SignatureSignatureSubject Alt. NameURI:S:ada:stake1vpu...p0u Intermediate CA's Key PairprivateSecretpublicSharedIntermediate Certificate (Intermediate CA)Subject`s NameIntermediate CA NameSubject`s PublicKeyPublic KeyIssuer`s NameRoot CA NameIssuer`s SignatureSignatureSubject Alt. NameURI:S:ada:stake1ngf...8dyURI:S:ada:cc_cold16cj..80v Entities Key PairprivateSecretpublicSharedIntermediate Certificate (Intermediate CA)Subject`s NameEntities NameSubject`s PublicKeyPublic KeyIssuer`s NameIntermediate CA NameIssuer`s SignatureSignatureSubject Alt. NameURI:S:ada:stake1ngf...v2qURI:S:ada:drep1ayt..80v Published Self SignPublishedSign ReferencesVerifiesPublishedVerifiesSignReferences + + + + + + + + + + + + + + + + + diff --git a/docs/src/catalyst-standards/draft-cips/role-registration/metadata-envelope.d2 b/docs/src/catalyst-standards/draft-cips/role-registration/metadata-envelope.d2 new file mode 100644 index 00000000000..db91c8472c2 --- /dev/null +++ b/docs/src/catalyst-standards/draft-cips/role-registration/metadata-envelope.d2 @@ -0,0 +1,138 @@ +vars: { + d2-config: { + layout-engine: elk + + # Terminal theme code + theme-id: 300 + } +} + +grid-columns: 1 + +title: |md + # Secure Metadata Envelope +| { + shape: text + # near: top-left + style: { + font-size: 25 + } +} + +signing-procedure: |md + # Signing procedure +| + +step_one: "" { + shape: rectangle + grid-columns: 1 + grid-gap: 10 + + step-1-2: |md + ## Prepare transaction body + + 1. Finalize the `transaction inputs` of the transaction. + 2. Generate a `blake2b_256()` hash of the finalized transaction inputs CBOR array. + | + + transaction-body-unsigned: "transaction-body-unsigned (minimum)" { + shape: sql_table + "0 = transaction inputs": "[ * [transaction hash, index] ]" + "1 = transaction outputs": "[ * transaction_output ]" + "2 = transaction fee": "coin (lovelace uint64)" + } +} + +step_three: "" { + shape: rectangle + grid-columns: 1 + grid-gap: 10 + + step-3-4-5: |md + ## Prepare the `auxiliary data` ready to sign. + + 3. Prepare all Auxiliary Data. + 4. Set `txn-input-hash` to the value computed in Step 2. + 5. PRESET the `validation signature` to 0s. + | + + metadata-ready-to-sign: { + shape: sql_table + "0 = purpose:": "128bit UUID V4 of the Metadata Purpose" + "1 = txn-input-hash:": "Blake2b-256 hash of the transaction inputs." + "10/11/12 = X509 chunks": "[ + x509_chunk ] - x509 Update Data." + "99 = validation signature": "0x00's" + } +} + +step_six: "" { + shape: rectangle + grid-columns: 1 + grid-gap: 10 + + step-6: |md + ## Sign the auxiliary data + + 6. Calculate the signature of the `metadata-ready-to-sign` using the Role 0 signing key. + 7. Replace the 0x00s in the `validation signature` with the calculated signature. + | + + metadata-signed: { + shape: sql_table + "0 = purpose:": "128bit UUID V4 of the Metadata Purpose" + "1 = txn-inputs-hash:": "Blake2b-256 hash of the transaction inputs." + "10/11/12 = X509 chunks": "[ + x509_chunk ] - x509 Update Data." + "99 = validation signature": "Signature calculated in step 6" + } +} + +step_eight: "" { + shape: rectangle + grid-columns: 1 + grid-gap: 10 + + step-8-9: |md + ## Finalize transaction ready to sign + + 8. Calculate and set the `auxiliary_data_hash` into the `transaction-body`. + 9. Optionally set `required signers` to ensure necessary extra witnesses are present. + | + + transaction-body-ready-to-signed: "transaction-body-ready-to-sign (minimum)" { + shape: sql_table + "0 = transaction inputs": "[ * [transaction hash, index] ]" + "1 = transaction outputs": "[ * transaction_output ]" + "2 = transaction fee": "coin (lovelace uint64)" + "7 = auxiliary_data_hash": "blake2b_256(auxiliary_data)" + "14 = required signers": "Optional list of extra witnesses required for transaction" + } +} + +step_ten: "" { + shape: rectangle + grid-columns: 1 + grid-gap: 10 + + step-10: |md + ## Sign the transaction + + 10. Sign the transaction with all necessary on-chain keys. + | + + transaction-body-signed: "transaction-body-signed (minimum)" { + shape: sql_table + "0 = transaction inputs": "[ * [transaction hash, index] ]" + "1 = transaction outputs": "[ * transaction_output ]" + "2 = transaction fee": "coin (lovelace uint64)" + "7 = auxiliary_data_hash": "blake2b_256(auxiliary_data)" + "14 = required signers": "Optional list of extra witnesses required for transaction" + } + + metadata-signed: { + shape: sql_table + "0 = purpose:": "128bit UUID V4 of the Metadata Purpose" + "1 = txn-inputs-hash:": "Hash of the transaction inputs" + "10/11/12 = X509 chunks": "[ + x509_chunk ] - x509 Update Data." + "99 = validation signatures": "Signature calculated in step 6" + } +} diff --git a/docs/src/catalyst-standards/draft-cips/role-registration/metadata-envelope.svg b/docs/src/catalyst-standards/draft-cips/role-registration/metadata-envelope.svg new file mode 100644 index 00000000000..147b3b6e88f --- /dev/null +++ b/docs/src/catalyst-standards/draft-cips/role-registration/metadata-envelope.svg @@ -0,0 +1,875 @@ +

Secure Metadata Envelope

+

Signing procedure

+

Prepare transaction body

+
    +
  1. Finalize the transaction inputs of the transaction.
    2. +
  2. Generate a blake2b_256() hash of the finalized transaction inputs CBOR array.
    3. +
+
transaction-body-unsigned (minimum)0 = transaction inputs[ * [transaction hash, index] ]1 = transaction outputs[ * transaction_output ]2 = transaction feecoin (lovelace uint64)

Prepare the auxiliary data ready to sign.

+
    +
  1. Prepare all Auxiliary Data.
    2. +
  2. Set txn-input-hash to the value computed in Step 2.
    3. +
  3. PRESET the validation signature to 0s.
    4. +
+
metadata-ready-to-sign0 = purpose:128bit UUID V4 of the Metadata Purpose1 = txn-input-hash:Blake2b-256 hash of the transaction inputs.10/11/12 = X509 chunks[ + x509_chunk ] - x509 Update Data.99 = validation signature0x00's

Sign the auxiliary data

+
    +
  1. Calculate the signature of the metadata-ready-to-sign using the Role 0 signing key.
    2. +
  2. Replace the 0x00s in the validation signature with the calculated signature.
    3. +
+
metadata-signed0 = purpose:128bit UUID V4 of the Metadata Purpose1 = txn-inputs-hash:Blake2b-256 hash of the transaction inputs.10/11/12 = X509 chunks[ + x509_chunk ] - x509 Update Data.99 = validation signatureSignature calculated in step 6

Finalize transaction ready to sign

+
    +
  1. Calculate and set the auxiliary_data_hash into the transaction-body.
    2. +
  2. Optionally set required signers to ensure necessary extra witnesses are present.
    3. +
+
transaction-body-ready-to-sign (minimum)0 = transaction inputs[ * [transaction hash, index] ]1 = transaction outputs[ * transaction_output ]2 = transaction feecoin (lovelace uint64)7 = auxiliary_data_hashblake2b_256(auxiliary_data)14 = required signersOptional list of extra witnesses required for transaction

Sign the transaction

+
    +
  1. Sign the transaction with all necessary on-chain keys.
    2. +
+
transaction-body-signed (minimum)0 = transaction inputs[ * [transaction hash, index] ]1 = transaction outputs[ * transaction_output ]2 = transaction feecoin (lovelace uint64)7 = auxiliary_data_hashblake2b_256(auxiliary_data)14 = required signersOptional list of extra witnesses required for transactionmetadata-signed0 = purpose:128bit UUID V4 of the Metadata Purpose1 = txn-inputs-hash:Hash of the transaction inputs10/11/12 = X509 chunks[ + x509_chunk ] - x509 Update Data.99 = validation signaturesSignature calculated in step 6 + + + + + + + + + diff --git a/docs/src/catalyst-standards/draft-cips/role-registration/x509-envelope.cddl b/docs/src/catalyst-standards/draft-cips/role-registration/x509-envelope.cddl index 6e1af83cb56..c9233d8ca71 100644 --- a/docs/src/catalyst-standards/draft-cips/role-registration/x509-envelope.cddl +++ b/docs/src/catalyst-standards/draft-cips/role-registration/x509-envelope.cddl @@ -1,52 +1,81 @@ ; An envelope for cardano metadata which holds the x509 metadata. -; We do thsi so that the underlying metadata is not restircted to -; cardano ledger implementation. +; The purpose of the Envelope is to ensure that metadata is not transportable between +; transactions. +; It ensures that it can be unambiguously validated that the auxiliary data attached to a transaction +; was intended for that transaction. +; By including the transactions input hash, the metadata is locked to the transaction as that set of +; transaction inputs are guaranteed to be unique under the UTXO model. +; It can not be moved to another transaction without being reconstructed as the transaction inputs would +; have changed. + +; This envelope is general in structure, it can be used to secure any auxiliary data, provided the +; Role 0 signing key is defined. As dApps control metadata, this ensures the data can eb authenticated +; independently by the dApp as belonging to a particular user. +; Once a Role 0 signing key is defined for a dApp purpose, then it is not necessary to redefine the +; x509 data if the envelope is only being used to secure the auxiliary data to a transaction itself. -; uses -x509_envelope = { +; The x509 envelope must be valid cardano metadata. +x509_envelope = $x509_envelope .within transaction_metadatum + +; Strcuture of the x509 envelope itself. +$x509_envelope /= { 0: purpose, ; What purpose does this metadata serve. - 1: required_signers_hash, ; A hash of the `required_signers` field from the transaction the metadata is posted with. - chunk_type: [ + x509_chunk ] - 99: [ + validation_signature ] ; The signature/s of the x509 certificate metadata record. + 1: tx_inputs_hash, ; A hash of the `transaction inputs` field from the transaction the metadata is posted with. + ? chunk_type => [ + x509_chunk ] ; Chunked x509 role registration data. + 99: validation_signature ; The signature of the x509 envelope plus all other auxiliary data. } +; x509 Role Registration data is chunked and optionally (preferably) compressed. +; This enables the x509 registration data to have a strucutre not supported by the +; underlying limitions of the on-chain metadatum implementation. +; As the x509 registration data may be large, compression is used to minimize on-chain space consumed. +; Best practice would be to compress the data with both brotli and zstd, and only store the +; smallest data set. `raw` storage would only be used if compression did not yield any benefits. +; However an application could choose to implement no compression or only one of either brotli/zstd. + ; Chunk Types - Allows to identify how the chunk data is compressed to save on-chain space. -; 2 : Chunk data is encoded raw -; 3 : Data is compressed with Brotli and then chunked. -; 4 : Data is compressed with ZSTD and then chunked. -chunk_type = (2..4) +chunk_types = ( + raw: 10 ; Data is just chunked, not compressed (raw) + brotli: 11 ; Data is compressed with BROTLI and then chunked. + zstd: 12 ; Data is compressed with ZSTD and then chunked. + reserved_3: 13 ; Reserved + reserved_4: 14 ; Reserved + reserved_5: 15 ; Reserved + reserved_6: 16 ; Reserved + reserved_7: 17 ; Reserved +) + +chunk_type = &chunk_types ; All valid chunk encodings, only one of these can be used at a time. ; An individual purpose or set or purposes -purpose = ( individual_purpose [ * individual_purpose ] ) +purpose = uuid-v4 ; A V4 UUID encoded as per https://datatracker.ietf.org/doc/html/rfc4122#section-4.1.2 -individual_purpose = (bytes .size (16)) +uuid-v4 = bytes .size 16 -; Transaction Required Signers Hash - Blake2b-224 -required_signers_hash = (bytes .size (28)) +; Hash of the transaction inputs this registration is attached to. +tx_inputs_hash = bytes .size 28 ; A single x509 chunk -x509_chunk = (bytes .size (0..64)) +; All chunks but the last must be 64 bytes in length (not enforced by the CDDL) +x509_min_chunk_size = 1 ; Can't have an empty chunk +x509_max_chunk_size = 64 ; Can't have a chunk bigger than 64 bytes +x509_chunk = bytes .size (x509_min_chunk_size .. x509_max_chunk_size); -; A Validation Signature -validation_signature = (bytes .size (0..64)) - -; Signatures are created by creating the x509_envelope with key `99`, but without all expected signatures set to 0x00's. -; Each signature is then computed over that binary data. -; Each blank signature is then replaced with the real signature. +; A list of x509 chunks +x509_chunks = [ + x509_full_chunk ] -; To validate the opposite occurs, the signatures are copied out of the envelope. -; The signature fields are set to 0x00's -; The resulting binary buffer is then checked against the signatures which were embedded. +; A Validation Signature +validation_signature = (bytes .size (1..64)) -; Explanation: -; The purpose of the Envelope is to ensure that metadata is not transportable between -; transactions. -; -; Transactions contain a `required_signers` field. -; By including a hash of that field within the metatdata, we can validated the transaction it was intended for. -; By signing the metadata envelope with the keys contained within the x509 chunks, we ensure that its not possible -; to transpose key certs from one transaction to another. +; This envelope can only be used if the current registration or a prior registration is valid +; AND they have defined for the purpose a Role 0 signing key. +; The `validation_signature` uses the Role 0 signing key . -; This envelope is general in structure, and that structure ensures metadata can not be transposed between transactions +; Definition of general cardano metadata, constrains what we can implement here: +transaction_metadatum = { * transaction_metadatum => transaction_metadatum } + / [ * transaction_metadatum ] + / int + / bytes .size (0..64) + / text .size (0..64) diff --git a/docs/src/catalyst-standards/draft-cips/role-registration/x509-roles.cddl b/docs/src/catalyst-standards/draft-cips/role-registration/x509-roles.cddl new file mode 100644 index 00000000000..2db58f07e8b --- /dev/null +++ b/docs/src/catalyst-standards/draft-cips/role-registration/x509-roles.cddl @@ -0,0 +1,123 @@ +; An envelope for cardano metadata which holds the x509 metadata. +; We do thsi so that the underlying metadata is not restircted to +; cardano ledger implementation. + +; uses +x509_roles = $x509_roles .within role-structure + +role-structure = [ role-version, role-body ] + +role-version = uint ; Version is an integer. +role-body = { + uint => any } ; General role body is a Map of integers to anything. + +; Version 0 of the role registration format. +$x509_roles /= x509-roles-v0 + +x509-roles-v0 = [ 0, x509-roles-v0-body ] + +x509-roles-v0-body = { + ? x509-certs => [ + x509_der_cert ], + ? c509-certs => [ + c509_cert ], + ? pub-keys => [ + simple-public-key-type ], + ? revocation-list => [ + revocation-set ], + ? attached-did => dids, + ? attached-vc => vcs, + ? role-set => role-data-set, + ? purpose-key-set => purpose-data-set, +} + +; x509 Certificates +x509-certs = 10 ; Unorderd bag of X509 DER Encoded certificates +x509_der_cert = bytes ; A DER Encoded X.509 Certificate (binary) + +; c509 Certificates +c509-certs = 20 ; Unorderd bag of C509 CBOR Encoded certificates +c509_cert = bytes .cbor any; A CBOR Encoded C.509 Certificate (binary) + +; Simple Public Keys +; These are just signing keys of the specified type, and are not true certs +; They are used for role keys or other uses where simple keys are sufficient +simple-public-keys = 30 ; Simple Public Keys + +simple-public-key-type = $simple-public-key-types +$simple-public-key-types /= ed25519-public-key +ed25519-public-key = #6.32773(bstr .size 32) ; Simple public keys must be tagged to identify their type. + +; x509/c509/simple key Revocation Lists +; Keys can only be revoked by the owner of the key or any issuer CA in the chain. +; Revocation becomes active AFTER certs in the same transaction are processed. +revocation-list = 40 ; Revocation List +revocation-entry = bytes .size 16; A blake2b-128 hash of the certificate/public key to be revoked +revocation-set = [ + revocation-entry ] + +; Digitial ID and Verifiable Credentials attached to this registration. + +attached-did = 50 ; DID/s attached to the certificates/on-chain identity +attached-vc = 51 ; Verifiable Credentials attached to the certificates/on-chain identity + +dids = [ + bytes ] ; One or multiple DIDs +vcs = [ + bytes ] ; One or multiple Verifiable Credentials + +; Role Registrations + +role-set = 100 + +role-data-set = [ + role-data ] + +role-data = { + 0: role-number, + ? 1: role-signing-key, + ? 2: role-encryption-key, + ? 3: payment-key, + * role-extended-data-keys => role-extended-data, +} + +; Role 0 is the ONLY manditory role. +; It defines the Validation certificate to be used to sign all registration metadata for this purpose for this identity. +validation-role = 0 +; role-signing-key must reference a certificate, and NOT a simple key. +; role-encryption-key must not be defined. +; There is no other data defined for this role. + +; Roles 1+ are purpose specific and not defined in this document. +role-number = uint +role-signing-key = key-reference +role-encryption-key = key-reference + +role-extended-data-keys = (10..99) + +role-extended-data = any +key-reference = key-local-ref / key-hash + +; Offset reference to a key defined in this registration. +; More efficient than a key hash. +key-local-ref = [ x509-certs + / c509-certs + / pub-keys, key-offset ] + +; Offset of the key in the specified set. 0 = first entry. +key-offset = uint + +; Reference to a key defined in an earlier registration +key-hash = bytes .size 16 + +; Reference to a transaction input/output as the payment key to use for a role +; Payment key (n) >= 0 = Use Transaction Input Key offset (n) as the payment key +; Payment key (n) < 0 = Use Transaction Output Key offstet -(n+1) as the payment key +; IFF a transaction output payment key is defined the payment address must also be in +; the required_signers of the transaction to ensure the payment address is owned and controlled +; by the entity posting the registration. +; If the referenced payment key does not exist in the transaction, or is not witnessed the entire +; registration is to be considered invalid. +payment-key = int + +; purpose specific data - Undefined here except for the key space +; Individual purposes can define these keys however they require. + +purpose-key-set = (first-purpose-key .. last-purpose-key) + +first-purpose-key = 200 +last-purpose-key = 299 +purpose-data-set = any + +; Note: any individual error in the role registration invalidates the entire registration. \ No newline at end of file diff --git a/docs/src/catalyst-standards/draft-cips/role-registration/x509-roles.d2 b/docs/src/catalyst-standards/draft-cips/role-registration/x509-roles.d2 new file mode 100644 index 00000000000..c0242d8a7a2 --- /dev/null +++ b/docs/src/catalyst-standards/draft-cips/role-registration/x509-roles.d2 @@ -0,0 +1,44 @@ +vars: { + d2-config: { + layout-engine: elk + + # Terminal theme code + theme-id: 300 + } +} + +classes: { + NONE: {style.opacity: 0} + RBAC_TABLE: { + shape: sql_table + style: { + border-radius: 15 + } + } +} + +title: |md + # x509 RBAC Metadata +| + +rbac: "x509 Role based Access Control" { + class: RBAC_TABLE + ? 10=x509 certs: "[ + DER Certs ]" + ? 20=c509 certs: "[ + CBOR Certs ]" + ? 30=public keys: "[ + Public Keys ]" + ? 40=revocation set: "[ + Revoked Cert hash]" + ? 50=DiD: "DiD???" + ? 51=Verifiable Credentials: "[ + VC??? ]" + "? 100=Role Data Set": "[ + Role Data ]" +} + +role_data: "Role Data" { + class: RBAC_TABLE + 0=role number: "uint" + ? 1=role-signing-key: "Key Reference" + ? 2=role-encryption-key: "Key Reference" + ? 3=payment-key: "OnChain Payment Key Reference" + ? 10-99=Role Specific Data: "Variable per Role" +} + +rbac."? 100=Role Data Set" -> role_data diff --git a/docs/src/catalyst-standards/draft-cips/role-registration/x509-roles.svg b/docs/src/catalyst-standards/draft-cips/role-registration/x509-roles.svg new file mode 100644 index 00000000000..e343da84d2f --- /dev/null +++ b/docs/src/catalyst-standards/draft-cips/role-registration/x509-roles.svg @@ -0,0 +1,836 @@ +

x509 RBAC Metadata

+
 x509 Role based Access Control? 10=x509 certs[ + DER Certs ]? 20=c509 certs[ + CBOR Certs ]? 30=public keys[ + Public Keys ]? 40=revocation set[ + Revoked Cert hash]? 50=DiDDiD???? 51=Verifiable Credentials[ + VC??? ]? 100=Role Data Set[ + Role Data ] Role Data0=role numberuint? 1=role-signing-keyKey Reference? 2=role-encryption-keyKey Reference? 3=payment-keyOnChain Payment Key Reference? 10-99=Role Specific DataVariable per Role + + + From 4f5e8dbc370db14b6726b8396448c15a835b8c0c Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Mon, 25 Mar 2024 21:06:36 +0700 Subject: [PATCH 34/66] docs(cips): Add full transaction/metadata relationship diagram --- .config/dictionaries/project.dic | 10 +- .../role-registration/cardano-transaction.svg | 2 +- .../role-registration/certificate-chain.svg | 2 +- .../role-registration/metadata-envelope.svg | 2 +- .../role-registration/x509-roles-complete.d2 | 198 ++++ .../role-registration/x509-roles-complete.svg | 926 ++++++++++++++++++ .../role-registration/x509-roles.svg | 2 +- 7 files changed, 1134 insertions(+), 8 deletions(-) create mode 100644 docs/src/catalyst-standards/draft-cips/role-registration/x509-roles-complete.d2 create mode 100644 docs/src/catalyst-standards/draft-cips/role-registration/x509-roles-complete.svg diff --git a/.config/dictionaries/project.dic b/.config/dictionaries/project.dic index 7cca967e2a1..05b0d8456a6 100644 --- a/.config/dictionaries/project.dic +++ b/.config/dictionaries/project.dic @@ -28,6 +28,7 @@ coti cryptoxide Cunego Cupertino +dalek dbsync delegators DIND @@ -65,12 +66,14 @@ Joaquín jorm jormungandr Jörmungandr +Keyhash lcov Leshiy lintfix localizable loguru mdlint +metadatum mgrybyk mithril mitigations @@ -114,6 +117,7 @@ rxdart saibatizoku schemathesis Schemathesis +Scripthash seckey sendfile slotno @@ -134,6 +138,8 @@ TXNZD unmanaged UTXO vitss +vkey +vkeywitness voteplan voteplans wallclock @@ -145,7 +151,3 @@ xctest xctestrun xcworkspace yoroi -dalek -Keyhash -Scripthash -vkey \ No newline at end of file diff --git a/docs/src/catalyst-standards/draft-cips/role-registration/cardano-transaction.svg b/docs/src/catalyst-standards/draft-cips/role-registration/cardano-transaction.svg index 3dcd2a8c4fb..fc7b8eafa75 100644 --- a/docs/src/catalyst-standards/draft-cips/role-registration/cardano-transaction.svg +++ b/docs/src/catalyst-standards/draft-cips/role-registration/cardano-transaction.svg @@ -1,4 +1,4 @@ -

x509 Transaction - Complete

+
Cardano Transactionbodytransaction bodyauxiliary_dataOption<auxiliary_data>witnessestransaction witness settransaction body0 = transaction inputs[ * [transaction hash, index] ]1 = transaction outputs[ * transaction_output ]2 = transaction feecoin (lovelace uint64)? 3 = Time to live [TTL]uint64? 4 = certificates[* certificate]? 5 = reward withdrawals{ * reward_account => coin (lovelace uint64) }? 6 = protocol parameter update[ proposed_protocol_parameter_updates, epoch ]? 7 = auxiliary_data_hash32 byte hash? 8 = validity interval startuint64? 9 = mint{ * policy_id => { * asset_name => a } }? 11 = script_data_hash32 byte hash? 13 = collateral inputs[ * [transaction hash, index] ]? 14 = required_signers[ * address key hash (blake2b-224) of signing public key ]? 15 = network_id0 or 1? 16 = collateral returntransaction_output (collateral return)? 17 = total collateralcoin (lovelace uint64)? 18 = reference inputsset<transaction_input>ROOT CERTIFICATE AUTHORITY (CA)auxiliary datametadata{ * uint => transaction_metadatum } : Optionalnative_script[ * native_script ] : Optionalplutus_v1[ * plutus_v1_script ] : Optionalplutus_v2[ * plutus_v2_script ] : Optionalx509 envelope metadata (Key 509)0purpose : 128bit UUID V4 of the Metadata Purpose1txn-inputs-hash : Hash of the transaction inputs10/11/12X509 chunks: [ + x509_chunk ] - x509 Update Data.99validation signature : Signature calculated in step 6 x509 Role based Access Control? 10=x509 certs[ + DER Certs ]? 20=c509 certs[ + CBOR Certs ]? 30=public keys[ + Public Keys ]? 40=revocation set[ + Revoked Cert hash]? 50=DiDDiD???? 51=Verifiable Credentials[ + VC??? ]? 100=Role Data Set[ + Role Data ] Role Data0=role numberuint? 1=role-signing-keyKey Reference? 2=role-encryption-keyKey Reference? 3=payment-keyOnChain Payment Key Reference? 10-99=Role Specific DataVariable per Role Role 0 - Metadata Validation Role0=role number01=role-signing-keyKey Reference Root CA's Key PairprivateSecretpublicSharedRoot Certificate (ROOT CA)Subject`s NameROOT CA NameSubject`s PublicKeyPublic KeyIssuer`s NameROOT CA NameIssuer`s SignatureSignatureSubject Alt NameURI:S:ada:stake1vpu...p0utransaction witness set? 0[* vkeywitness ]? 1[* native_script]? 2[* bootstrap_witness]? 3[* plutus_v1_script]? 4[* plutus_data]? 5[* redeemer]? 6[* plutus_v2_script]vkeywitnessvkeyED25519-Bip32 Public Key [32 Bytes]signatureED25519-Bip32 Signature of Transaction [64 bytes] bodyauxiliary_data(optional)509Requiredblake2b_256() blake2b_256()Published Self Signcontainscontains Signtransaction mustbe witnessed bywitnesses + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/src/catalyst-standards/draft-cips/role-registration/x509-roles.svg b/docs/src/catalyst-standards/draft-cips/role-registration/x509-roles.svg index e343da84d2f..587bbf3cf80 100644 --- a/docs/src/catalyst-standards/draft-cips/role-registration/x509-roles.svg +++ b/docs/src/catalyst-standards/draft-cips/role-registration/x509-roles.svg @@ -1,4 +1,4 @@ -

Label = 509

+
metadata-signed0 : purpose128bit UUID V4 of the Metadata Purpose1 : txn-inputs-hashHash of the transaction inputs?2 : previous_transaction_idHash of the immediately proceeding registration in a series of updates (optional)10/11/12 = X509 chunks[ + x509_chunk ] - x509 Update Data (Preferably compressed).99 = validation signatureSignature over the entire Auxiliary data attached to the transaction. + + + diff --git a/docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/x509-envelope.cddl b/docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/x509-envelope.cddl index c9233d8ca71..ba5aa75bea9 100644 --- a/docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/x509-envelope.cddl +++ b/docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/x509-envelope.cddl @@ -21,10 +21,19 @@ x509_envelope = $x509_envelope .within transaction_metadatum $x509_envelope /= { 0: purpose, ; What purpose does this metadata serve. 1: tx_inputs_hash, ; A hash of the `transaction inputs` field from the transaction the metadata is posted with. + ?2: previous_transaction_id ; Previous transaction ID in the chain of registration updates for this user. ? chunk_type => [ + x509_chunk ] ; Chunked x509 role registration data. 99: validation_signature ; The signature of the x509 envelope plus all other auxiliary data. } +; hash of the previous transaction in the registration chain. +; There can only be one registration for a user for a purpose that does not have a previous transaction id. +; This would be the first. +; Once that is posted, all updates must properly maintian the chain. +; Dangling registrations for the same purpose are ignored. +previous_transaction_id = $hash32 +$hash32 /= bytes .size 32 + ; x509 Role Registration data is chunked and optionally (preferably) compressed. ; This enables the x509 registration data to have a strucutre not supported by the ; underlying limitions of the on-chain metadatum implementation. From 4cc75779deae26b91dc6fdb1ce60206ce9a6acdc Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Tue, 2 Apr 2024 21:36:24 +0700 Subject: [PATCH 39/66] Update docs/src/catalyst-standards/draft-cips/c509-plutus-restricted-certificate/c509-cert-plutus-restricted.cddl Co-authored-by: bkioshn <35752733+bkioshn@users.noreply.github.com> --- .../c509-cert-plutus-restricted.cddl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/catalyst-standards/draft-cips/c509-plutus-restricted-certificate/c509-cert-plutus-restricted.cddl b/docs/src/catalyst-standards/draft-cips/c509-plutus-restricted-certificate/c509-cert-plutus-restricted.cddl index 3252c52d46c..c8743fc0537 100644 --- a/docs/src/catalyst-standards/draft-cips/c509-plutus-restricted-certificate/c509-cert-plutus-restricted.cddl +++ b/docs/src/catalyst-standards/draft-cips/c509-plutus-restricted-certificate/c509-cert-plutus-restricted.cddl @@ -17,7 +17,7 @@ TBSCertificate = ( subject: Name, ; Reference to on-chain keys related to this certificate subjectPublicKeyAlgorithm: AlgorithmIdentifier, ; Must be 12 = Ed25519 subjectPublicKey: subjectPublicKey, ; Ed25519 public key - extensions: Extensions, ; No extensions aer currently supported must be set to [] + extensions: Extensions, ; No extensions are currently supported must be set to [] issuerSignatureAlgorithm: AlgorithmIdentifier, ; Must be 12 = Ed25519 ) From 7c67290281021ce46d61e83087ee939dfeef30cb Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Tue, 2 Apr 2024 21:37:18 +0700 Subject: [PATCH 40/66] Update docs/src/catalyst-standards/draft-cips/c509-plutus-restricted-certificate/c509-cert-plutus-restricted.cddl Co-authored-by: bkioshn <35752733+bkioshn@users.noreply.github.com> --- .../c509-cert-plutus-restricted.cddl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/catalyst-standards/draft-cips/c509-plutus-restricted-certificate/c509-cert-plutus-restricted.cddl b/docs/src/catalyst-standards/draft-cips/c509-plutus-restricted-certificate/c509-cert-plutus-restricted.cddl index c8743fc0537..295f75565ef 100644 --- a/docs/src/catalyst-standards/draft-cips/c509-plutus-restricted-certificate/c509-cert-plutus-restricted.cddl +++ b/docs/src/catalyst-standards/draft-cips/c509-plutus-restricted-certificate/c509-cert-plutus-restricted.cddl @@ -45,7 +45,7 @@ Attribute = ( subjectPublicKey = bytes .size (32..32); Ed25519 public key stored in bytes, adjust size of this if other key types are supported. ; This is a completely custom Attribute for the RelativeDistringuishedName which is only for use with Plutus scripts. -; attributeType = The type of cardano key we associate with this certificate. +; attributeType = The type of Cardano key we associate with this certificate. ; proof = Does the transaction require proof that the key is owned by the transaction signer? ; attributeValue = The cardano public key hash of the attribute type From e0d8346e1987064e839f2804b176f3716f57bb76 Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Tue, 2 Apr 2024 21:37:32 +0700 Subject: [PATCH 41/66] Update docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/x509-roles.cddl Co-authored-by: bkioshn <35752733+bkioshn@users.noreply.github.com> --- .../draft-cips/x509-role-registration-metadata/x509-roles.cddl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/x509-roles.cddl b/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/x509-roles.cddl index 2db58f07e8b..34e2f57813c 100644 --- a/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/x509-roles.cddl +++ b/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/x509-roles.cddl @@ -72,7 +72,7 @@ role-data = { * role-extended-data-keys => role-extended-data, } -; Role 0 is the ONLY manditory role. +; Role 0 is the ONLY mandatory role. ; It defines the Validation certificate to be used to sign all registration metadata for this purpose for this identity. validation-role = 0 ; role-signing-key must reference a certificate, and NOT a simple key. From c17ceffa885fd507ec1bc8a64a53d7c35988cc9d Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Tue, 2 Apr 2024 21:39:09 +0700 Subject: [PATCH 42/66] Update docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/x509-roles.cddl Co-authored-by: bkioshn <35752733+bkioshn@users.noreply.github.com> --- .../x509-role-registration-metadata/x509-roles.cddl | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/x509-roles.cddl b/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/x509-roles.cddl index 34e2f57813c..e0013a2004e 100644 --- a/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/x509-roles.cddl +++ b/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/x509-roles.cddl @@ -1,6 +1,6 @@ -; An envelope for cardano metadata which holds the x509 metadata. -; We do thsi so that the underlying metadata is not restircted to -; cardano ledger implementation. +; An envelope for Cardano metadata which holds the x509 metadata. +; We do this so that the underlying metadata is not restircted to +; Cardano ledger implementation. ; uses x509_roles = $x509_roles .within role-structure From 46a383947b68015f6e3e46e85da2576e490d45ee Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Tue, 2 Apr 2024 21:39:22 +0700 Subject: [PATCH 43/66] Update docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/x509-envelope.cddl Co-authored-by: bkioshn <35752733+bkioshn@users.noreply.github.com> --- .../draft-cips/x509-envelope-metadata/x509-envelope.cddl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/x509-envelope.cddl b/docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/x509-envelope.cddl index ba5aa75bea9..fb793972bca 100644 --- a/docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/x509-envelope.cddl +++ b/docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/x509-envelope.cddl @@ -82,7 +82,7 @@ validation_signature = (bytes .size (1..64)) ; The `validation_signature` uses the Role 0 signing key . -; Definition of general cardano metadata, constrains what we can implement here: +; Definition of general Cardano metadata, constrains what we can implement here: transaction_metadatum = { * transaction_metadatum => transaction_metadatum } / [ * transaction_metadatum ] / int From d067e40e9e8811092e73e6de7dcc48fd8b16c7bb Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Tue, 2 Apr 2024 21:39:43 +0700 Subject: [PATCH 44/66] Update docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/x509-envelope.cddl Co-authored-by: bkioshn <35752733+bkioshn@users.noreply.github.com> --- .../draft-cips/x509-envelope-metadata/x509-envelope.cddl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/x509-envelope.cddl b/docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/x509-envelope.cddl index fb793972bca..d6a66e9caef 100644 --- a/docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/x509-envelope.cddl +++ b/docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/x509-envelope.cddl @@ -9,7 +9,7 @@ ; have changed. ; This envelope is general in structure, it can be used to secure any auxiliary data, provided the -; Role 0 signing key is defined. As dApps control metadata, this ensures the data can eb authenticated +; Role 0 signing key is defined. As dApps control metadata, this ensures the data can be authenticated ; independently by the dApp as belonging to a particular user. ; Once a Role 0 signing key is defined for a dApp purpose, then it is not necessary to redefine the ; x509 data if the envelope is only being used to secure the auxiliary data to a transaction itself. From b4a87c1afcb5f5bda3e7c5e52b865c513537adea Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Tue, 2 Apr 2024 21:39:55 +0700 Subject: [PATCH 45/66] Update docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/x509-envelope.cddl Co-authored-by: bkioshn <35752733+bkioshn@users.noreply.github.com> --- .../draft-cips/x509-envelope-metadata/x509-envelope.cddl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/x509-envelope.cddl b/docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/x509-envelope.cddl index d6a66e9caef..ff6b0abc292 100644 --- a/docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/x509-envelope.cddl +++ b/docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/x509-envelope.cddl @@ -1,4 +1,4 @@ -; An envelope for cardano metadata which holds the x509 metadata. +; An envelope for Cardano metadata which holds the x509 metadata. ; The purpose of the Envelope is to ensure that metadata is not transportable between ; transactions. ; It ensures that it can be unambiguously validated that the auxiliary data attached to a transaction From 8e586778e65c661dc9642a8111efac15e5fc908a Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Tue, 2 Apr 2024 21:40:21 +0700 Subject: [PATCH 46/66] Update docs/src/catalyst-standards/draft-cips/c509-plutus-restricted-certificate/c509-cert-plutus-restricted.cddl Co-authored-by: bkioshn <35752733+bkioshn@users.noreply.github.com> --- .../c509-cert-plutus-restricted.cddl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/catalyst-standards/draft-cips/c509-plutus-restricted-certificate/c509-cert-plutus-restricted.cddl b/docs/src/catalyst-standards/draft-cips/c509-plutus-restricted-certificate/c509-cert-plutus-restricted.cddl index 295f75565ef..d2ceb0a7bde 100644 --- a/docs/src/catalyst-standards/draft-cips/c509-plutus-restricted-certificate/c509-cert-plutus-restricted.cddl +++ b/docs/src/catalyst-standards/draft-cips/c509-plutus-restricted-certificate/c509-cert-plutus-restricted.cddl @@ -47,7 +47,7 @@ subjectPublicKey = bytes .size (32..32); Ed25519 public key stored in bytes, adj ; This is a completely custom Attribute for the RelativeDistringuishedName which is only for use with Plutus scripts. ; attributeType = The type of Cardano key we associate with this certificate. ; proof = Does the transaction require proof that the key is owned by the transaction signer? -; attributeValue = The cardano public key hash of the attribute type +; attributeValue = The Cardano public key hash of the attribute type CardanoPublicKey = ( attributeType: &cardanoKeyTypes proof: bool, attributeValue: bytes .size (28..28) ) From 89eb0a218250e81ea9e50869275331f792b63e14 Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Wed, 3 Apr 2024 11:20:08 +0700 Subject: [PATCH 47/66] docs(cips): Fix time and algorithm comments --- .../c509-cert-plutus-restricted.cddl | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/src/catalyst-standards/draft-cips/c509-plutus-restricted-certificate/c509-cert-plutus-restricted.cddl b/docs/src/catalyst-standards/draft-cips/c509-plutus-restricted-certificate/c509-cert-plutus-restricted.cddl index d2ceb0a7bde..e4fe93fdb16 100644 --- a/docs/src/catalyst-standards/draft-cips/c509-plutus-restricted-certificate/c509-cert-plutus-restricted.cddl +++ b/docs/src/catalyst-standards/draft-cips/c509-plutus-restricted-certificate/c509-cert-plutus-restricted.cddl @@ -12,13 +12,13 @@ TBSCertificate = ( c509CertificateType: &c509CertificateTypeValues, ; Always 0 certificateSerialNumber: CertificateSerialNumber, ; Can be ignored/set to 0 or used as intended. issuer: Name, ; This could be an on-chain reference to the issuer cert, what would be the best way? Transaction hash/cert hash? - validityNotBefore: Time, ; c509 uses UTC, we can use slot# to simplify - validityNotAfter: Time, ; c509 uses UTC, we can use slot# to simplify + validityNotBefore: Time, ; c509 uses UTC + validityNotAfter: Time, ; c509 uses UTC subject: Name, ; Reference to on-chain keys related to this certificate - subjectPublicKeyAlgorithm: AlgorithmIdentifier, ; Must be 12 = Ed25519 + subjectPublicKeyAlgorithm: AlgorithmIdentifier, ; Must be int(12) = Ed25519 subjectPublicKey: subjectPublicKey, ; Ed25519 public key extensions: Extensions, ; No extensions are currently supported must be set to [] - issuerSignatureAlgorithm: AlgorithmIdentifier, ; Must be 12 = Ed25519 + issuerSignatureAlgorithm: AlgorithmIdentifier, ; Must be int(12) = Ed25519 ) ; 0 = Native CBOR Certificate type From 172ffbfba2f773da5c58ead947ecef9e3cd7dc14 Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Wed, 3 Apr 2024 13:16:44 +0700 Subject: [PATCH 48/66] build(frontend): Relax flutter/dart version requirements to last minor release --- .../example/pubspec.yaml | 4 +- .../catalyst_voices_assets/pubspec.yaml | 4 +- .../catalyst_voices_blocs/pubspec.yaml | 44 +++++++++---------- .../catalyst_voices_localization/pubspec.yaml | 2 +- .../catalyst_voices_repositories/pubspec.yaml | 6 +-- .../catalyst_voices_services/pubspec.yaml | 4 +- .../catalyst_voices_shared/pubspec.yaml | 13 +++--- .../catalyst_voices_view_models/pubspec.yaml | 6 +-- catalyst_voices/pubspec.yaml | 10 ++--- .../catalyst_analysis/example/pubspec.yaml | 2 +- .../catalyst_analysis/pubspec.yaml | 2 +- melos.yaml | 10 ++--- pubspec.yaml | 2 +- 13 files changed, 54 insertions(+), 55 deletions(-) diff --git a/catalyst_voices/packages/catalyst_voices_assets/example/pubspec.yaml b/catalyst_voices/packages/catalyst_voices_assets/example/pubspec.yaml index 40336f3b7ab..7288ed22e5f 100644 --- a/catalyst_voices/packages/catalyst_voices_assets/example/pubspec.yaml +++ b/catalyst_voices/packages/catalyst_voices_assets/example/pubspec.yaml @@ -5,7 +5,7 @@ publish_to: none environment: sdk: ">=3.2.6 <4.0.0" - flutter: 3.19.5 + flutter: 3.19.0 dependencies: catalyst_voices_assets: @@ -14,4 +14,4 @@ dependencies: sdk: flutter flutter: - uses-material-design: true \ No newline at end of file + uses-material-design: true diff --git a/catalyst_voices/packages/catalyst_voices_assets/pubspec.yaml b/catalyst_voices/packages/catalyst_voices_assets/pubspec.yaml index 1f15832aa5f..14a62462651 100644 --- a/catalyst_voices/packages/catalyst_voices_assets/pubspec.yaml +++ b/catalyst_voices/packages/catalyst_voices_assets/pubspec.yaml @@ -5,7 +5,7 @@ publish_to: none environment: sdk: ">=3.2.6 <4.0.0" - flutter: 3.19.5 + flutter: 3.19.0 dependencies: flutter: @@ -43,4 +43,4 @@ flutter_gen: outputs: class_name: VoicesColors inputs: - - assets/colors/colors.xml \ No newline at end of file + - assets/colors/colors.xml diff --git a/catalyst_voices/packages/catalyst_voices_blocs/pubspec.yaml b/catalyst_voices/packages/catalyst_voices_blocs/pubspec.yaml index 1a2d0d64f27..4a2086af4e0 100644 --- a/catalyst_voices/packages/catalyst_voices_blocs/pubspec.yaml +++ b/catalyst_voices/packages/catalyst_voices_blocs/pubspec.yaml @@ -5,30 +5,30 @@ publish_to: none environment: sdk: ">=3.2.6 <4.0.0" - flutter: 3.19.5 + flutter: 3.19.0 dependencies: - bloc: ^8.1.2 - bloc_concurrency: ^0.2.2 - catalyst_voices_models: - path: ../catalyst_voices_models - catalyst_voices_repositories: - path: ../catalyst_voices_repositories - catalyst_voices_services: - path: ../catalyst_voices_services - catalyst_voices_view_models: - path: ../catalyst_voices_view_models - collection: ^1.17.1 - equatable: ^2.0.5 - flutter: - sdk: flutter - formz: ^0.7.0 - get_it: ^7.6.7 - meta: ^1.10.0 - result_type: ^0.2.0 + bloc: ^8.1.2 + bloc_concurrency: ^0.2.2 + catalyst_voices_models: + path: ../catalyst_voices_models + catalyst_voices_repositories: + path: ../catalyst_voices_repositories + catalyst_voices_services: + path: ../catalyst_voices_services + catalyst_voices_view_models: + path: ../catalyst_voices_view_models + collection: ^1.17.1 + equatable: ^2.0.5 + flutter: + sdk: flutter + formz: ^0.7.0 + get_it: ^7.6.7 + meta: ^1.10.0 + result_type: ^0.2.0 dev_dependencies: - bloc_test: ^9.1.4 - catalyst_analysis: + bloc_test: ^9.1.4 + catalyst_analysis: path: ../../../catalyst_voices_packages/catalyst_analysis - test: ^1.24.9 + test: ^1.24.9 diff --git a/catalyst_voices/packages/catalyst_voices_localization/pubspec.yaml b/catalyst_voices/packages/catalyst_voices_localization/pubspec.yaml index ec80ae6fb2f..f84bee54adc 100644 --- a/catalyst_voices/packages/catalyst_voices_localization/pubspec.yaml +++ b/catalyst_voices/packages/catalyst_voices_localization/pubspec.yaml @@ -5,7 +5,7 @@ publish_to: none environment: sdk: ">=3.2.6 <4.0.0" - flutter: 3.19.5 + flutter: 3.19.0 dependencies: flutter: diff --git a/catalyst_voices/packages/catalyst_voices_repositories/pubspec.yaml b/catalyst_voices/packages/catalyst_voices_repositories/pubspec.yaml index 2e9dc961f66..85e08957999 100644 --- a/catalyst_voices/packages/catalyst_voices_repositories/pubspec.yaml +++ b/catalyst_voices/packages/catalyst_voices_repositories/pubspec.yaml @@ -5,7 +5,7 @@ publish_to: none environment: sdk: ">=3.2.6 <4.0.0" - flutter: 3.19.5 + flutter: 3.19.0 dependencies: catalyst_voices_models: @@ -18,6 +18,6 @@ dependencies: rxdart: ^0.27.7 dev_dependencies: - catalyst_analysis: + catalyst_analysis: path: ../../../catalyst_voices_packages/catalyst_analysis - test: ^1.24.9 + test: ^1.24.9 diff --git a/catalyst_voices/packages/catalyst_voices_services/pubspec.yaml b/catalyst_voices/packages/catalyst_voices_services/pubspec.yaml index 3594867114b..2c0fdb4df4f 100644 --- a/catalyst_voices/packages/catalyst_voices_services/pubspec.yaml +++ b/catalyst_voices/packages/catalyst_voices_services/pubspec.yaml @@ -5,7 +5,7 @@ publish_to: none environment: sdk: ">=3.2.6 <4.0.0" - flutter: 3.19.5 + flutter: 3.19.0 dependencies: chopper: ^7.2.0 @@ -22,4 +22,4 @@ dev_dependencies: chopper_generator: ^7.2.0 json_serializable: ^6.7.1 swagger_dart_code_generator: ^2.15.2 - test: ^1.24.9 \ No newline at end of file + test: ^1.24.9 diff --git a/catalyst_voices/packages/catalyst_voices_shared/pubspec.yaml b/catalyst_voices/packages/catalyst_voices_shared/pubspec.yaml index e9e7014efbf..056d53e8fc5 100644 --- a/catalyst_voices/packages/catalyst_voices_shared/pubspec.yaml +++ b/catalyst_voices/packages/catalyst_voices_shared/pubspec.yaml @@ -4,8 +4,8 @@ version: 0.1.0+1 publish_to: none environment: - sdk: '>=3.3.3 <4.0.0' - flutter: 3.19.5 + sdk: ">=3.3.0 <4.0.0" + flutter: 3.19.0 dependencies: flutter: @@ -13,9 +13,8 @@ dependencies: web: ^0.5.0 dev_dependencies: - catalyst_analysis: + catalyst_analysis: path: ../../../catalyst_voices_packages/catalyst_analysis - flutter_test: - sdk: flutter - test: ^1.24.9 - + flutter_test: + sdk: flutter + test: ^1.24.9 diff --git a/catalyst_voices/packages/catalyst_voices_view_models/pubspec.yaml b/catalyst_voices/packages/catalyst_voices_view_models/pubspec.yaml index c5cbffb382b..247d5605d0f 100644 --- a/catalyst_voices/packages/catalyst_voices_view_models/pubspec.yaml +++ b/catalyst_voices/packages/catalyst_voices_view_models/pubspec.yaml @@ -5,7 +5,7 @@ publish_to: none environment: sdk: ">=3.2.6 <4.0.0" - flutter: 3.19.5 + flutter: 3.19.0 dependencies: equatable: ^2.0.5 @@ -14,6 +14,6 @@ dependencies: formz: ^0.7.0 dev_dependencies: - catalyst_analysis: + catalyst_analysis: path: ../../../catalyst_voices_packages/catalyst_analysis - test: ^1.24.9 \ No newline at end of file + test: ^1.24.9 diff --git a/catalyst_voices/pubspec.yaml b/catalyst_voices/pubspec.yaml index 130a51b8721..15320d1965f 100644 --- a/catalyst_voices/pubspec.yaml +++ b/catalyst_voices/pubspec.yaml @@ -4,8 +4,8 @@ version: 0.1.0+1 publish_to: none environment: - sdk: '>=3.3.3 <4.0.0' - flutter: 3.19.5 + sdk: ">=3.3.0 <4.0.0" + flutter: 3.19.0 dependencies: animated_text_kit: ^4.2.2 @@ -44,9 +44,9 @@ dev_dependencies: build_verify: ^3.1.0 catalyst_analysis: git: - url: https://github.com/input-output-hk/catalyst-voices.git - path: catalyst_voices_packages/catalyst_analysis - ref: 3431f7b + url: https://github.com/input-output-hk/catalyst-voices.git + path: catalyst_voices_packages/catalyst_analysis + ref: 3431f7b flutter_test: sdk: flutter go_router_builder: ^2.4.1 diff --git a/catalyst_voices_packages/catalyst_analysis/example/pubspec.yaml b/catalyst_voices_packages/catalyst_analysis/example/pubspec.yaml index 3b5ad986b44..ee9b9ad454c 100644 --- a/catalyst_voices_packages/catalyst_analysis/example/pubspec.yaml +++ b/catalyst_voices_packages/catalyst_analysis/example/pubspec.yaml @@ -4,7 +4,7 @@ description: A project that showcases how to enable the recommended lints for Ca publish_to: none environment: - sdk: '>=3.3.3 <4.0.0' + sdk: '>=3.3.0 <4.0.0' dev_dependencies: catalyst_analysis: diff --git a/catalyst_voices_packages/catalyst_analysis/pubspec.yaml b/catalyst_voices_packages/catalyst_analysis/pubspec.yaml index a68dd8d09f8..603c1876aa2 100644 --- a/catalyst_voices_packages/catalyst_analysis/pubspec.yaml +++ b/catalyst_voices_packages/catalyst_analysis/pubspec.yaml @@ -3,4 +3,4 @@ version: 1.0.0 description: Lint rules for Dart and Flutter used internally at Catalyst. environment: - sdk: '>=3.3.3 <4.0.0' + sdk: '>=3.3.0 <4.0.0' diff --git a/melos.yaml b/melos.yaml index eff14ec4b09..dbcba7de824 100644 --- a/melos.yaml +++ b/melos.yaml @@ -12,8 +12,8 @@ command: workspaceChangelog: true bootstrap: environment: - sdk: '>=3.3.0 <4.0.0' - flutter: 3.19.5 + sdk: ">=3.3.0 <4.0.0" + flutter: 3.19.0 dependencies: bloc_concurrency: ^0.2.2 bloc: ^8.1.2 @@ -33,8 +33,8 @@ scripts: description: Run all static analysis checks. format: - run: melos exec dart format . --fix - description: Run `dart format` for all packages. + run: melos exec dart format . --fix + description: Run `dart format` for all packages. format-check: run: melos exec dart format . --set-exit-if-changed @@ -76,4 +76,4 @@ scripts: run: flutter pub get exec: concurrency: 6 - description: Install all dependencies \ No newline at end of file + description: Install all dependencies diff --git a/pubspec.yaml b/pubspec.yaml index 1decd7e9e98..a6af3c302dd 100644 --- a/pubspec.yaml +++ b/pubspec.yaml @@ -1,7 +1,7 @@ name: catalyst_voices_workspace environment: - sdk: '>=3.3.3 <4.0.0' + sdk: '>=3.3.0 <4.0.0' dev_dependencies: melos: ^5.2.2 From 863a6a0330fe33f0207c00a07c59778be4c5f535 Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Fri, 5 Apr 2024 14:12:43 +0700 Subject: [PATCH 49/66] docs(cips): wip --- .../x509-rbac-signing-with-cip30/cip-xxxx.md | 10 +++++++++- .../x509-role-registration-metadata/cip-xxxx.md | 5 +++-- 2 files changed, 12 insertions(+), 3 deletions(-) diff --git a/docs/src/catalyst-standards/draft-cips/x509-rbac-signing-with-cip30/cip-xxxx.md b/docs/src/catalyst-standards/draft-cips/x509-rbac-signing-with-cip30/cip-xxxx.md index 066f2e22723..3526b370cda 100644 --- a/docs/src/catalyst-standards/draft-cips/x509-rbac-signing-with-cip30/cip-xxxx.md +++ b/docs/src/catalyst-standards/draft-cips/x509-rbac-signing-with-cip30/cip-xxxx.md @@ -65,5 +65,13 @@ and answer any questions that the CPS poses for potential solutions. ### Implementation Plan +## References + ## Copyright - + +This CIP is licensed under [CC-BY-4.0] + +Code samples and reference material are licensed under [Apache 2.0] + +[CC-BY-4.0]: https://creativecommons.org/licenses/by/4.0/legalcode +[Apache 2.0]: https://www.apache.org/licenses/LICENSE-2.0.html diff --git a/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/cip-xxxx.md b/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/cip-xxxx.md index c7ea4567977..d0976c4f8e9 100644 --- a/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/cip-xxxx.md +++ b/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/cip-xxxx.md @@ -120,8 +120,7 @@ We intentionally take advantage of the significant existing code bases and infra #### Certificate formats -x.509 certificates can be encoded in - +x.509 certificates can be encoded in We encode x.509 certificates using [CBOR Encoded X.509 Certificates][C509], Each certificate includes its on-chain anchor (public key). The on-chain anchors currently envisioned are: @@ -596,6 +595,8 @@ and answer any questions that the CPS poses for potential solutions. ### Implementation Plan +## References + ## Copyright This CIP is licensed under [CC-BY-4.0] From 974d832667f4a305a272658f3a42f915fce5cf3c Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Wed, 10 Apr 2024 10:20:13 +0700 Subject: [PATCH 50/66] fix(cips): rename draft x509 envelope CIP so its easier to identify --- .../x509-envelope-metadata/cip-509A.md | 229 ++++++++++++++++++ 1 file changed, 229 insertions(+) create mode 100644 docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/cip-509A.md diff --git a/docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/cip-509A.md b/docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/cip-509A.md new file mode 100644 index 00000000000..54dac6ddffc --- /dev/null +++ b/docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/cip-509A.md @@ -0,0 +1,229 @@ +--- +CIP: /? +Title: x509 Replayability Protection Envelope +Category: MetaData +Status: Proposed +Authors: + - Steven Johnson +Implementors: [] +Discussions: + - https://github.com/cardano-foundation/cips/pulls/? +Created: 2023-10-24 +License: CC-BY-4.0 +--- + +## Abstract + +x509 Certificate metadata and related metadata within an x509 Registration/Update transaction must be +protected against replayability. + +## Motivation: why is this CIP necessary? + +x509 certificate registration necessarily references data within the transaction body that it is attached to. +Preventing replayability of the verbatim Auxiliary data attached to a transaction prevents the relationships +between those references being altered and closes a potential attack vector where an unrelated registration update +is attached to a different transaction. + +Rather than define an explicit issue with potential replayability of Metadata, we simply seek to prevent it +to close off a whole category of potential attacks. + +## Specification + +The [x509 Metadata Envelope CDDL] defines the technical specification of the Metadata Envelope. +The following description provides more information and context to that formal specification. +Where this description and that specification are in disagreement, the specification prevails. + +The metadata envelope has the following basic structure: + +![x509 Secure Metadata Envelope structure](images/metadata-envelope-structure.svg) + +The purpose of this data is to lock a particular set of Auxiliary data verifiably to its original transaction. +It can not be permitted to take teh Auxiliary data to another transaction and just attach it without it being detectable. + +Currently, this detection can NOT be done on-chain by ledger rules, and this metadata is designed to be processed +by off-chain processors of this information. + +### Detailed description of the fields in the metadata and their purpose + +The metadata is encoded as a CBOR map, and follows the [specification for the encoding of all Cardano metadata]. + +#### Key: 0 = Purpose + +Purpose is defined by the consuming dApp. +It allows dApps to have their own privately named and managed namespace for certificates. +The x509 specifications presented here do not define how certificates must be created. +Nor the purpose they are used for, that is within control of the dApp. +These specifications define a universal framework to implement such systems from. + +For each set of "Purposes" that a dapp has for role based access or off-chain identity to on-chain identity management +the dApp will define a V4 UUID. +There is no central repository of these, though a dApp may publish the ID it uses and what its used for. +The reason UUID V4 is chosen here is if properly chosen, they can be self assigned without fear of collision +with another dApp and eliminate the need for a central registry to manage them. + +A dApp can define multiple purposes to segment RBAC functions by class. +For example, Project Catalyst defines the following two Purposes: + +| UUID-V4 | Purpose | +| --- | --- | +| ca7a1457-ef9f-4c7f-9c74-7f8c4a4cfa6c | Project Catalyst User Role Registrations | +| ca7ad312-a19b-4412-ad53-2a36fb14e2e5 | Project Catalyst Admin Role Registrations | + +The reason in this case for having two purposes for the same application is to allow the rules +governing registration to be easier managed between the groups. +It also allows Admins to have a distinct identity when they are just users of the system. +dApps are free top have as many "purposes" defined as suits their goals. + +#### Key 1: txn-inputs-hash + +This is a hash of the transaction inputs field from the transaction this auxiliary data was original attached to. +This hash anchors the auxiliary data to a particular transaction, if the auxiliary data is moved to a new transaction +it is impossible for the txn-inputs-hash to remain the same, as UTXO's can only be spent once. + +This is a key to preventing replayability of the metadata, but is not enough by itself as it needs to be able to be +made immutable, such that any change to this field can be detected. + +#### Key 2: previous_transaction_id + +This is a 32 byte hash of the previous transaction in a chain of registration updates made by the same user. +The only registration which may not have it for a single user is their first. +Once their first registration is made, they may only update it. +Any subsequent update for that user that is not properly chained to the previous transaction will be ignored as invalid. + +The user is identified by their Role 0 key, which must be defined in the first registration. +The Role 0 key also includes a reference to an on-chain key, such as a stake key hash. +This is important to establish the verifiability of the link between the registrations and the transaction itself. + +#### Keys 10, 11 or 12 - x509 Chunked Data + +Except for the first registration, the chunked data is optional. +For example, if this metadata is simply being used to lock auxiliary data to a transaction there does not need to be +any actual role or certificate updates. + +The data required to register certificates or roles could be large. +The [specification for the encoding of all Cardano metadata] also introduces difficulties in encoding x509 certificates. + +The contents of the x509 RABC Registration data stored in this key is documented separately. +Its exact contents are not important for this specification except to note, that it will always define at least: + +* 1 Role 0 signing key MUST always be defined. + * And that key MUST be associated with a on-chain key such as a stake address hash. +* The RBAC Data will have references to the transaction it is attached to, + and it can not be fully interpreted independent of the transaction. + +To save space and overcome the metadata encoding limitations, x509 RBAC data is preferable encoded as described: + +1. The x509 Role Registration Data is prepared and encoded with [dCBOR]. + This is the raw encoded registration data. +2. The raw encoded registration data is then compressed with [Brotli]. + This is the Brotli compressed registration data. +3. The raw encoded registration data is then compressed with [ZSTD]. + This is the ZSTD compressed registration data. +4. Which ever data is smallest, Raw, Brotli compressed or ZStd compressed is then cut into 64 byte chunks. + All chunks must contain 64 bytes except for the last which can contain the residual. +5. These chunks are then encoded in an array of 64 byte long byte strings. + The appropriate key is used to identify the compression used. + * 10 = Raw, no compression + * 11 = Brotli Compressed + * 12 = ZSTD Compressed + +Due to the potential size of x509 certificates compression is mandatory where it will reduce the space of the encoded data. +dApps can, if they choose, only support either Brotli or ZSTD and not trial compress the data. +However they must never store data compressed if the compressed size is larger than the raw size. +This can happen if the data is small and not very compressible, due to overhead in the codec data stream. + +The specification reserves keys 13-17 for future compression schemes. +Even though there are multiple keys defined, ONLY 1 may be used at a time. +There is only a single list of x509 chunks and the key is used to define the compression used only. + +ie, it is invalid to use key 10 and 12 at the same time in the same envelope. + +#### Key 99 - Validation Signature + +Key 99 contains the signature which can be verified with the signing key recorded against role 0. + +It is a signature over the [entire auxiliary data] that will be attached to the transaction. +This includes not only the transactions metadata, but all attached scripts. + +As the auxiliary data key 99 is part of the auxiliary data, we end up with a catch-22. +We can't sign the data because we do not know what data will be stored in the signature field. +To mitigate this problem, the size of the signature will be known in advanced, based on the signature algorithm. +When the unsigned auxiliary data is prepared, the appropriate storage for the signature is pre-allocated +in the metadata, and is set to 0x00's. + +The signature is calculated over this unsigned data, and the pre-allocated signature storage is replaced with the signature itself. + +This ensures that there is no alteration to the auxiliary data in form or structure. +Validating the signature then is as simple as: + +1. removing the signature data from the auxiliary data; +2. setting the storage for the signature back to 0, and; +3. validating the signature on the reconstructed unsigned auxiliary data. + +### Validating the Auxiliary Data is attached to the correct transaction + +The Transaction will have 3 pieces of information that must be validated to ensure the attached metadata +is carried with the correct transaction. + +1. The UTXO Inputs when hashed MUST == [Key 1 - Transaction Inputs Hash](#key-1-txn-inputs-hash) +2. The [auxiliary data hash] must equal the hash of the actual auxiliary data. + 1. This is likely always true as it would be validated by the ledger rules. +3. The [vkeywitness] set MUST include a signature over the transaction with the key associated with Role 0. + 1. Note: Role 0 may have multiple associated keys, in which case there must be a witness for all of them. + 2. A missing witness means it is not possible to validate the auxiliary data truly was built for this transaction. + +## Rationale: how does this CIP achieve its goals? + +This specification creates a signed set of interlocking data between a transaction and its auxiliary data. +The interlock is constructed to avoid any catch-22 in setting up a transaction and to minimize complexity. + +By signing off-chain data with an off-chain key, we simplify the process of signing auxiliary data, +this allows us to sign all the data in a way suitable to the needs of the method and not limited to any on-chain restrictions. + +The off-chain key is explicitly associated with an on-chain key, such that signing with the on-chain key over +the registration transaction provides proof that they two keys are related and can be used interchangeably, + +Once constructed in the way documented, the auxiliary data may not be posted in a different transaction without it being detected. + +It is not currently possible to detect this on-chain, as plutus does not have the necessary functionality to allow it +to inspect auxiliary data, except under very limited circumstances. +However, the purpose of this envelope is to ensure that off-chain construction of off +chain certificates and dApp role registration is secure. + +This specification meets that criteria. + +## Path to Active + +### Acceptance Criteria + + +### Implementation Plan + + +## References + +* [Cardano Metadata CDDL Specification][specification for the encoding of all Cardano metadata] +* [Cardano Auxiliary Data CDDL Specification][entire auxiliary data] +* [Cardano Transaction Auxiliary Data Hash Specification][auxiliary data hash] +* [Cardano vKeyWitness Specification][vkeywitness] +* [Deterministic CBOR Encoding][dCBOR] +* [Brotli Data Compression][Brotli] +* [ZSTD Data Compression][ZSTD] + +## Copyright + +This CIP is licensed under [CC-BY-4.0] + +Code samples and reference material are licensed under [Apache 2.0] + + +[CC-BY-4.0]: https://creativecommons.org/licenses/by/4.0/legalcode +[Apache 2.0]: https://www.apache.org/licenses/LICENSE-2.0.html +[x509 Metadata Envelope CDDL]: ./x509_envelope.cddl +[specification for the encoding of all Cardano metadata]: https://github.com/IntersectMBO/cardano-ledger/blob/ab8d57cf43be912a336e872b68d1a2526c93dc6a/eras/conway/impl/cddl-files/conway.cddl#L511-L531 +[dCBOR]: https://datatracker.ietf.org/doc/draft-mcnally-deterministic-cbor/ +[Brotli]: https://github.com/google/brotli +[ZSTD]: https://github.com/facebook/zstd +[entire auxiliary data]: https://github.com/IntersectMBO/cardano-ledger/blob/ab8d57cf43be912a336e872b68d1a2526c93dc6a/eras/conway/impl/cddl-files/conway.cddl#L521-L531 +[auxiliary data hash]: https://github.com/IntersectMBO/cardano-ledger/blob/ab8d57cf43be912a336e872b68d1a2526c93dc6a/eras/conway/impl/cddl-files/conway.cddl#L60 +[vkeywitness]: https://github.com/IntersectMBO/cardano-ledger/blob/ab8d57cf43be912a336e872b68d1a2526c93dc6a/eras/conway/impl/cddl-files/conway.cddl#L436 From 65b398691f789a9440ea531958a87f120a40be01 Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Wed, 10 Apr 2024 10:20:39 +0700 Subject: [PATCH 51/66] docs(cips): WIP updates to x509 roles --- .../draft-cips/images/x509-roles.d2 | 44 -- .../x509-envelope-metadata/cip-xxxx.md | 229 ------- .../cip-xxxx.md | 481 ++++----------- .../images/x509-roles.d2 | 49 ++ .../images/x509-roles.svg | 562 +++++++++--------- .../x509-roles.cddl | 22 +- 6 files changed, 443 insertions(+), 944 deletions(-) delete mode 100644 docs/src/catalyst-standards/draft-cips/images/x509-roles.d2 delete mode 100644 docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/cip-xxxx.md create mode 100644 docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/images/x509-roles.d2 rename docs/src/catalyst-standards/draft-cips/{ => x509-role-registration-metadata}/images/x509-roles.svg (50%) diff --git a/docs/src/catalyst-standards/draft-cips/images/x509-roles.d2 b/docs/src/catalyst-standards/draft-cips/images/x509-roles.d2 deleted file mode 100644 index c0242d8a7a2..00000000000 --- a/docs/src/catalyst-standards/draft-cips/images/x509-roles.d2 +++ /dev/null @@ -1,44 +0,0 @@ -vars: { - d2-config: { - layout-engine: elk - - # Terminal theme code - theme-id: 300 - } -} - -classes: { - NONE: {style.opacity: 0} - RBAC_TABLE: { - shape: sql_table - style: { - border-radius: 15 - } - } -} - -title: |md - # x509 RBAC Metadata -| - -rbac: "x509 Role based Access Control" { - class: RBAC_TABLE - ? 10=x509 certs: "[ + DER Certs ]" - ? 20=c509 certs: "[ + CBOR Certs ]" - ? 30=public keys: "[ + Public Keys ]" - ? 40=revocation set: "[ + Revoked Cert hash]" - ? 50=DiD: "DiD???" - ? 51=Verifiable Credentials: "[ + VC??? ]" - "? 100=Role Data Set": "[ + Role Data ]" -} - -role_data: "Role Data" { - class: RBAC_TABLE - 0=role number: "uint" - ? 1=role-signing-key: "Key Reference" - ? 2=role-encryption-key: "Key Reference" - ? 3=payment-key: "OnChain Payment Key Reference" - ? 10-99=Role Specific Data: "Variable per Role" -} - -rbac."? 100=Role Data Set" -> role_data diff --git a/docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/cip-xxxx.md b/docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/cip-xxxx.md deleted file mode 100644 index 54dac6ddffc..00000000000 --- a/docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/cip-xxxx.md +++ /dev/null @@ -1,229 +0,0 @@ ---- -CIP: /? -Title: x509 Replayability Protection Envelope -Category: MetaData -Status: Proposed -Authors: - - Steven Johnson -Implementors: [] -Discussions: - - https://github.com/cardano-foundation/cips/pulls/? -Created: 2023-10-24 -License: CC-BY-4.0 ---- - -## Abstract - -x509 Certificate metadata and related metadata within an x509 Registration/Update transaction must be -protected against replayability. - -## Motivation: why is this CIP necessary? - -x509 certificate registration necessarily references data within the transaction body that it is attached to. -Preventing replayability of the verbatim Auxiliary data attached to a transaction prevents the relationships -between those references being altered and closes a potential attack vector where an unrelated registration update -is attached to a different transaction. - -Rather than define an explicit issue with potential replayability of Metadata, we simply seek to prevent it -to close off a whole category of potential attacks. - -## Specification - -The [x509 Metadata Envelope CDDL] defines the technical specification of the Metadata Envelope. -The following description provides more information and context to that formal specification. -Where this description and that specification are in disagreement, the specification prevails. - -The metadata envelope has the following basic structure: - -![x509 Secure Metadata Envelope structure](images/metadata-envelope-structure.svg) - -The purpose of this data is to lock a particular set of Auxiliary data verifiably to its original transaction. -It can not be permitted to take teh Auxiliary data to another transaction and just attach it without it being detectable. - -Currently, this detection can NOT be done on-chain by ledger rules, and this metadata is designed to be processed -by off-chain processors of this information. - -### Detailed description of the fields in the metadata and their purpose - -The metadata is encoded as a CBOR map, and follows the [specification for the encoding of all Cardano metadata]. - -#### Key: 0 = Purpose - -Purpose is defined by the consuming dApp. -It allows dApps to have their own privately named and managed namespace for certificates. -The x509 specifications presented here do not define how certificates must be created. -Nor the purpose they are used for, that is within control of the dApp. -These specifications define a universal framework to implement such systems from. - -For each set of "Purposes" that a dapp has for role based access or off-chain identity to on-chain identity management -the dApp will define a V4 UUID. -There is no central repository of these, though a dApp may publish the ID it uses and what its used for. -The reason UUID V4 is chosen here is if properly chosen, they can be self assigned without fear of collision -with another dApp and eliminate the need for a central registry to manage them. - -A dApp can define multiple purposes to segment RBAC functions by class. -For example, Project Catalyst defines the following two Purposes: - -| UUID-V4 | Purpose | -| --- | --- | -| ca7a1457-ef9f-4c7f-9c74-7f8c4a4cfa6c | Project Catalyst User Role Registrations | -| ca7ad312-a19b-4412-ad53-2a36fb14e2e5 | Project Catalyst Admin Role Registrations | - -The reason in this case for having two purposes for the same application is to allow the rules -governing registration to be easier managed between the groups. -It also allows Admins to have a distinct identity when they are just users of the system. -dApps are free top have as many "purposes" defined as suits their goals. - -#### Key 1: txn-inputs-hash - -This is a hash of the transaction inputs field from the transaction this auxiliary data was original attached to. -This hash anchors the auxiliary data to a particular transaction, if the auxiliary data is moved to a new transaction -it is impossible for the txn-inputs-hash to remain the same, as UTXO's can only be spent once. - -This is a key to preventing replayability of the metadata, but is not enough by itself as it needs to be able to be -made immutable, such that any change to this field can be detected. - -#### Key 2: previous_transaction_id - -This is a 32 byte hash of the previous transaction in a chain of registration updates made by the same user. -The only registration which may not have it for a single user is their first. -Once their first registration is made, they may only update it. -Any subsequent update for that user that is not properly chained to the previous transaction will be ignored as invalid. - -The user is identified by their Role 0 key, which must be defined in the first registration. -The Role 0 key also includes a reference to an on-chain key, such as a stake key hash. -This is important to establish the verifiability of the link between the registrations and the transaction itself. - -#### Keys 10, 11 or 12 - x509 Chunked Data - -Except for the first registration, the chunked data is optional. -For example, if this metadata is simply being used to lock auxiliary data to a transaction there does not need to be -any actual role or certificate updates. - -The data required to register certificates or roles could be large. -The [specification for the encoding of all Cardano metadata] also introduces difficulties in encoding x509 certificates. - -The contents of the x509 RABC Registration data stored in this key is documented separately. -Its exact contents are not important for this specification except to note, that it will always define at least: - -* 1 Role 0 signing key MUST always be defined. - * And that key MUST be associated with a on-chain key such as a stake address hash. -* The RBAC Data will have references to the transaction it is attached to, - and it can not be fully interpreted independent of the transaction. - -To save space and overcome the metadata encoding limitations, x509 RBAC data is preferable encoded as described: - -1. The x509 Role Registration Data is prepared and encoded with [dCBOR]. - This is the raw encoded registration data. -2. The raw encoded registration data is then compressed with [Brotli]. - This is the Brotli compressed registration data. -3. The raw encoded registration data is then compressed with [ZSTD]. - This is the ZSTD compressed registration data. -4. Which ever data is smallest, Raw, Brotli compressed or ZStd compressed is then cut into 64 byte chunks. - All chunks must contain 64 bytes except for the last which can contain the residual. -5. These chunks are then encoded in an array of 64 byte long byte strings. - The appropriate key is used to identify the compression used. - * 10 = Raw, no compression - * 11 = Brotli Compressed - * 12 = ZSTD Compressed - -Due to the potential size of x509 certificates compression is mandatory where it will reduce the space of the encoded data. -dApps can, if they choose, only support either Brotli or ZSTD and not trial compress the data. -However they must never store data compressed if the compressed size is larger than the raw size. -This can happen if the data is small and not very compressible, due to overhead in the codec data stream. - -The specification reserves keys 13-17 for future compression schemes. -Even though there are multiple keys defined, ONLY 1 may be used at a time. -There is only a single list of x509 chunks and the key is used to define the compression used only. - -ie, it is invalid to use key 10 and 12 at the same time in the same envelope. - -#### Key 99 - Validation Signature - -Key 99 contains the signature which can be verified with the signing key recorded against role 0. - -It is a signature over the [entire auxiliary data] that will be attached to the transaction. -This includes not only the transactions metadata, but all attached scripts. - -As the auxiliary data key 99 is part of the auxiliary data, we end up with a catch-22. -We can't sign the data because we do not know what data will be stored in the signature field. -To mitigate this problem, the size of the signature will be known in advanced, based on the signature algorithm. -When the unsigned auxiliary data is prepared, the appropriate storage for the signature is pre-allocated -in the metadata, and is set to 0x00's. - -The signature is calculated over this unsigned data, and the pre-allocated signature storage is replaced with the signature itself. - -This ensures that there is no alteration to the auxiliary data in form or structure. -Validating the signature then is as simple as: - -1. removing the signature data from the auxiliary data; -2. setting the storage for the signature back to 0, and; -3. validating the signature on the reconstructed unsigned auxiliary data. - -### Validating the Auxiliary Data is attached to the correct transaction - -The Transaction will have 3 pieces of information that must be validated to ensure the attached metadata -is carried with the correct transaction. - -1. The UTXO Inputs when hashed MUST == [Key 1 - Transaction Inputs Hash](#key-1-txn-inputs-hash) -2. The [auxiliary data hash] must equal the hash of the actual auxiliary data. - 1. This is likely always true as it would be validated by the ledger rules. -3. The [vkeywitness] set MUST include a signature over the transaction with the key associated with Role 0. - 1. Note: Role 0 may have multiple associated keys, in which case there must be a witness for all of them. - 2. A missing witness means it is not possible to validate the auxiliary data truly was built for this transaction. - -## Rationale: how does this CIP achieve its goals? - -This specification creates a signed set of interlocking data between a transaction and its auxiliary data. -The interlock is constructed to avoid any catch-22 in setting up a transaction and to minimize complexity. - -By signing off-chain data with an off-chain key, we simplify the process of signing auxiliary data, -this allows us to sign all the data in a way suitable to the needs of the method and not limited to any on-chain restrictions. - -The off-chain key is explicitly associated with an on-chain key, such that signing with the on-chain key over -the registration transaction provides proof that they two keys are related and can be used interchangeably, - -Once constructed in the way documented, the auxiliary data may not be posted in a different transaction without it being detected. - -It is not currently possible to detect this on-chain, as plutus does not have the necessary functionality to allow it -to inspect auxiliary data, except under very limited circumstances. -However, the purpose of this envelope is to ensure that off-chain construction of off -chain certificates and dApp role registration is secure. - -This specification meets that criteria. - -## Path to Active - -### Acceptance Criteria - - -### Implementation Plan - - -## References - -* [Cardano Metadata CDDL Specification][specification for the encoding of all Cardano metadata] -* [Cardano Auxiliary Data CDDL Specification][entire auxiliary data] -* [Cardano Transaction Auxiliary Data Hash Specification][auxiliary data hash] -* [Cardano vKeyWitness Specification][vkeywitness] -* [Deterministic CBOR Encoding][dCBOR] -* [Brotli Data Compression][Brotli] -* [ZSTD Data Compression][ZSTD] - -## Copyright - -This CIP is licensed under [CC-BY-4.0] - -Code samples and reference material are licensed under [Apache 2.0] - - -[CC-BY-4.0]: https://creativecommons.org/licenses/by/4.0/legalcode -[Apache 2.0]: https://www.apache.org/licenses/LICENSE-2.0.html -[x509 Metadata Envelope CDDL]: ./x509_envelope.cddl -[specification for the encoding of all Cardano metadata]: https://github.com/IntersectMBO/cardano-ledger/blob/ab8d57cf43be912a336e872b68d1a2526c93dc6a/eras/conway/impl/cddl-files/conway.cddl#L511-L531 -[dCBOR]: https://datatracker.ietf.org/doc/draft-mcnally-deterministic-cbor/ -[Brotli]: https://github.com/google/brotli -[ZSTD]: https://github.com/facebook/zstd -[entire auxiliary data]: https://github.com/IntersectMBO/cardano-ledger/blob/ab8d57cf43be912a336e872b68d1a2526c93dc6a/eras/conway/impl/cddl-files/conway.cddl#L521-L531 -[auxiliary data hash]: https://github.com/IntersectMBO/cardano-ledger/blob/ab8d57cf43be912a336e872b68d1a2526c93dc6a/eras/conway/impl/cddl-files/conway.cddl#L60 -[vkeywitness]: https://github.com/IntersectMBO/cardano-ledger/blob/ab8d57cf43be912a336e872b68d1a2526c93dc6a/eras/conway/impl/cddl-files/conway.cddl#L436 diff --git a/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/cip-xxxx.md b/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/cip-xxxx.md index d0976c4f8e9..868b488bddc 100644 --- a/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/cip-xxxx.md +++ b/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/cip-xxxx.md @@ -61,6 +61,8 @@ However forcing all authentication through a wallet has several primary disadvan * Wallets only are guaranteed to provide `signData` if they implement CIP30, and that only allows a single signature. * There are multiple keys controlled by a wallet and its useful to ensure that all keys reflected are valid. +* Its equally important to ensure that registrations prove custody/ownership of certain on-chain identities, + such as registered stake address or drep registration. * Metadata in a transaction is inaccessible to plutus scripts. * Wallets could present raw data to be signed to the user, and that makes the UX poor because the user would have difficulty knowing what they are signing. @@ -68,6 +70,7 @@ However forcing all authentication through a wallet has several primary disadvan * Putting chain keys in metadata can be redundant if those keys are already in the transaction. * Some authentication needs to change with regularity, such as authentication tokens to a backend service, and this would require potentially excessive wallet interactions. + This would lower UX quality and could impact participation. The proposal here is to register dApp specific keys and identity, but strongly associate it with on-chain identity, such as Stake Public Keys, Payment Keys and Drep Keys, such that off chain interactions can be fully authenticated, @@ -75,13 +78,21 @@ and only on-chain interaction requires interaction with a Wallet. ## Specification +Role registration is encapsulated inside a [x509 Envelope](../x509-envelope-metadata/cip-xxxx.md) metadata record. +This enables the data to both be compressed, saving on-chain space and also to have more expressivity and +less restrictions vs raw on-chain metadata. + +This specification covers the general use of the x509 registration format and is not specific to any dApp. +dApps can utilize any subset of the features defined herein, and dApps define their own roles. + In order to maintain a robust set of role registration capabilities Role registration involves: 1. Creation of a root certificate for a user or set of users and associating it with an on-chain source of trust. 2. Obtaining for each user of a dapp, or a set of users, their root certificate. 3. Deriving role specific keys from the root certificate. 4. Optionally registering for those roles on-chain. -5. Signing and/or encrypting data with the root certificate or a derived key, or a certificate issued by a previously registered root certificate. +5. Signing and/or encrypting data with the root certificate or a derived key, or a certificate issued by a previously + registered root certificate. Effectively we map the blockchain as PKI (Public Key Infrastructure) and define the methods a dapp can use to exploit this PKI. @@ -120,37 +131,18 @@ We intentionally take advantage of the significant existing code bases and infra #### Certificate formats -x.509 certificates can be encoded in - -We encode x.509 certificates using [CBOR Encoded X.509 Certificates][C509], Each certificate includes its on-chain anchor (public key). -The on-chain anchors currently envisioned are: - -1. Stake Address -2. dRep Key - -The transaction that is submitted on-chain which includes the certificate in its metadata MUST be witnessed by it's on-chain anchor. -This is used to prove that the certificate and on-chain anchor are controlled by the same entity. -It prevents replay attacks where people could try and associate a different on-chain anchor with a certificate. +x.509 certificates can be encoded in: ---- - -Note: **The information below is to be reviewed in-light of the above** - -Role registration is achieved by using two metadata records attached to the same transaction. +* Binary DER format +* [CBOR Encoded X.509 Certificates][C509]. -### Metadata Labels +### Metadata Structure -| Metadata Label | Description | -| --- | --- | -| `7222` | The RBAC Metadata Label | -| `7223` | The RBAC Metadata witness set Label | +The formal definition of the x509 certificate payload is [here](./x509-roles.cddl). -Both pieces of metadata must be present in the same transaction for the registration to be valid. +The format can be visualized as: -`7222` AND `7223` define this Metadata as being Role Registration Metadata. -These Metadata key should not be used for another purpose. - -Note: **7222 is RBAC when decoded using the telephone ITU E.161 standard** +![x509 Registration Format](./images/x509-roles.svg) ### Metadata Encoding @@ -170,391 +162,136 @@ Each dApp may have further validity requirements beyond those stated herein. At a high level, Role registration will collect the following data: -1. A [role public key or non-empty list of role public keys](#subkey-1---role-specific-public-key-or-role-public-key-array); -2. A [stake address for the network that this transaction is submitted to](#subkey-2---stake-public-key); -3. An *Optional* [Shelley payment address](). -4. A [nonce]() that identifies that most recent registration. -5. The [role]() being registered. -6. A [dApp ID]() which defines the dApp the registration belongs to. -6. An *Optional* [expiry timestamp](). -7. Optional dApp defined [extended registration metadata](). - -The formal specification for the `7222` Metadata is [CIPxxxx Metadata CDDL][]. - -Informally, all Registrations follow the same generalized Format (Non-Normative): - -```cbor -7222: { - // Role Public Key or Role Public Key Array - 1: #6.32773(h'a6a3c0447aeb9cc54cf6422ba32b294e5e1c3ef6d782f2acff4a70694c4d1663') ; or - [#6.32773(h'A71A8700248D4C91E01A2A2CB5F4F0E664F084EB761C6792AEDD28160C1E403C'), - #6.32773(h'C606D983C5545800FAF20519D21988AA0A13271BA12BA9A8643FCFAD58697C97')] ; or - [ - [#6.32773(h'A71A8700248D4C91E01A2A2CB5F4F0E664F084EB761C6792AEDD28160C1E403C'), 50], - [#6.32773(h'C606D983C5545800FAF20519D21988AA0A13271BA12BA9A8643FCFAD58697C97'), 50] - ] - // Stake Public Key - 2: #6.32773(h'ad4b948699193634a39dd56f779a2951a24779ad52aa7916f6912b8ec4702cee'), - // Payment Address - 3: #6.???h'00588e8e1d18cba576a4d35758069fe94e53f638b6faf7c07b8abd2bc5c5cdee47b60edc7772855324c85033c638364214cbfc6627889f81c4', - // nonce - 4: #6.32770 h'018d45d8deb3a1b171f6b38577ecee20', // ULID - // Role - 5: 0, - // dApp ID (UUID or ULID) - 6: #6.37 h'a3c12b1c98af4ee8b54278e77906c0fc'; or // UUID - #6.32770 h'018d1d2acaf04486be189dbc5ae35e51', // ULID - // Expires - Optional - 7: #6.1(0), - // dApp Defined Metadata - Optional - 100+: -} -``` - -Keys between `8` and `99` are reserved for any future extensions to this specification. -They must not be defined by any dApp for private use. -These keys, if defined, will be defined by a CIP which extends this base specification. - -Keys above `100` are reserved for dApp specific use, and may be defined either formally by a CIP or informally by any dApp. -General parsers of this data should accept, but not otherwise interpret keys `100`+ unless they specifically understand -the requirements of the identified dApp. - -### Subkey 1 - Role Specific Public Key OR Role Public Key Array - -Subkey 1 is either: - -* A Single [Role Specific Public Key](#subkey-1---role-key---single-role-specific-public-key); OR -* A [Optionally Weighted List of Role Specific Public Keys](#subkey-1---role-key---list-of-role-keys). - -#### SubKey 1 - Role Key - Single Role Specific Public Key - -The Role Key is an [Ed25519-BIP32][CIP0003] public key. - -This is represented as a CBOR Byte-string, 32 bytes long. -It is tagged with `#6.???` to unambiguously identify the key type. -This is to allow the specification to evolve in a forward compatible manor if new key types are introduced. - -Any and All authoritative actions performed under the registered Role MUST be signed with an owned Role Key. -How the dApp signs the data and what format that data or signature takes is not defined in this CIP. - -The Witness data informs if the Role key is being used by reference, and is not owned by the registration, -or is owned and controlled by the registration. -This distinction is important in cases where a Role is being delegated to another registration. -The definition of the `purpose` will declare if it is valid for a particular Role to delegate or not and is -outside the scope of this specification. - -Role keys MUST be derived using the following specific key derivation path. -This is to allow Key recovery across compatible wallets. -An implementation will be non-conforming to this specification if it does not use the defined Key derivation path. - -It is valid for multiple Stake addresses to register with the same Role key, but they MUST prove ownership of the key -otherwise it will be identified as a delegation. -The dApp defines the limits of this relationship, and that can differ on a role by role basis. - -Role keys MUST, as far as practically possible, be unique to a dApp to ensure they are not improperly used across dApps. -The aim is for a Role key to unambiguously declare the intention of the user to act with their role. -See [Key Derivation](#key-derivation) for details on how the Role key MUST be derived from the master key of the wallet. - -Other than the fact that a registration unambiguously associates one or more Stake addresses to a Role Specific Public Key, -this CIP does not define how that is validated for any particular dApp or Role. -A later section of this CIP will demonstrate possible validation scenarios that a dApp can adopt. - -Example: - -```cbor -h'a6a3c0447aeb9cc54cf6422ba32b294e5e1c3ef6d782f2acff4a70694c4d1663' -``` - -##### Key Derivation - -It is REQUIRED that path based key derivation be used to generate the Role Specific Public Key. -If a wallet is incapable of using path based key derivation as defined by this specification it is -not capable of conforming to the requirements of this specification. - -Key derivation is used to avoid linking Role access keys directly with Cardano spending keys. -It also provides a mechanism to unambiguously identify the role being asserted when data is signed. - -The Role Specific key derivation path must start with a specific segment: - -Path based key derivation is limited to 31 bits, per path component. -The [dApp ID] is 128 bits. -It is required that the Role key be, as far as practically possible, unique amongst dApps. -This is to prevent a Role from one dApp being misused by another, either intentionally or inadvertently. - -However key derivation is limited to 31 bits, accordingly, the [dApp ID] will be hashed with Blake2B and a -31 bit digest will be produced. -The aim is to as far as practical cause dApps to have distinct Role keys under normal circumstances. - -`m / 7222' / 1815' / account' / chain' / hash(dApp ID) / role` - -* `7222'` : The registration metadata field key from this CIP. -* `1815'` : The year Ada Lovelace was born - Identifies this key as being for Cardano. -* `account'` : The voters account -* `chain'` : The chain on which the voter is registering. -* `hash(dapp ID)` : The [hashed](#hashdapp-id) [dApp ID] -* `role` : The role being registered for. - -Note: It is specifically required that the Role Key NOT CHANGE for the same dApp UUID/Purpose for any compliant Wallet. -This is because its possible to make both single and array role registrations, and its critical the key be the same in these. -It also critical that the Role keys be freely transferable and recoverable across wallets. -The necessity of this will be expanded on when the witness is discussed below. - -##### hash(dapp ID) - -The [dApp ID] will be reduced to 31 bits by using Blake2B with a 32 bit digest over the [dApp ID]. - -To ensure the hardening bit is not set, the high bit of the resultant hash will be forced to 0. +1. An [optional list](#x509-certificate-lists) of DER format x509 certificates. +2. An [optional list](#x509-certificate-lists) of [CBOR Encoded X.509 Certificates][C509] +3. An [optional list](#simple-public-keys) list of tagged simple public keys. +4. An [optional certificate revocation](#certificate-revocation-list) set. +5. An optional set of role registration data. -```text - hash(dapp ID) == blake2b_32(dapp ID) & 0x7FFFFFFF -``` +### x509 Certificate Lists -While 31 bits is small, and could be subject to a collision attack, the intention here is not to prevent -deliberately contrived collisions but to disambiguate dApps under normal circumstances. -As the [dApp ID] is not controllable, a malicious dApp could simply use the same dApp ID as another. -Therefore it is not possible to protect against a collision and the [dApp ID] is not a security mechanism -in any event. +There can be two lists of certificates. +They are functionally identical and differ only in the format of the certificate itself. -#### SubKey 1 - Role Key - List of Role Keys +DER Format certificates are used when the only certificate source is a legacy off-chain certificate. +These are not preferred because they can be transcoded into c509 format, and are usually larger than their c509 equivalent. +However, it is recognized that legacy support for x509 DER format certificates is important, and they are supported. -Catalyst has the need to associate role registrations as a list, and optionally to have those registrations weighted. -For example, this will be used to: +Preferably all certificates will either be uniquely encoded as c509 encoded certificates, +or will be transcoded from a DER format x509 certificate into it's c509 equivalent. -* Define Voter Delegation to representatives. -* Define Co-Proposers for Catalyst proposals. +The certificate lists are unsorted, and are simply a method of publishing a new certificate on-chain. -It is generally useful to be able to associate multiple role public keys together. +The only feature about the certificate that impacts the role registration is that certificates +may embed references to on-chain keys. -How these role registration lists are used and validated by any dApp are outside the scope of this CIP. -The [individual role keys](#subkey-1---role-key---single-role-specific-public-key) within a Role Key list are defined -according to this specification above. +In the case where a certificate does embed a reference to an on-chain key, +the key SHOULD be present in the witness set of the transaction. +Individual dApps can strengthen this requirement to MUST. -There are two possible General formats of a role registration list is: +By including the Signature in the transaction, we are able to make a verifiable link between the +off-chain certificate and the on-chain identity. +This can not be forged. -* [Simple Role Key List](#simple-role-key-list) -* [Weighted Role Key List](#weighted-role-key-list) +### Simple Public Keys -A simple list is equivalent to a weighted role key list. -If a Weighted list is expected in a registration, and a simple list is found in a registration, -then it is interpreted as a weighted role key list where each entry is equally weighted. -This can be used to decrease the size of the registration metadata by eliding the weights when -they are all the same. +Rather than require full certificates, dApps can use simple public keys. +The simple public key list is for that purpose. +The list acts as an array, the index in the array is the offset of the key. -However, the converse is not true. -If a Role expects a simple role key list, and a weighted role key list is found in the registration then -the format is invalid. -This is because it is not possible to determine the expected behavior of the unused weights. +CBOR allows for array elements to be skipped or marked as undefined. -* [\](#subkey-1---role-key---single-role-specific-public-key) : is the role specific public key defined above. - * This key can belong to the registering user themselves; or - * Can belong to another user, either from the same or a different role registration. - * Must be for the same [dApp UUID][dApp-UUID]. (Cross dApp Registrations is not defined or supported by this CIP). -* : is a 4-byte unsigned integer (CBOR major type 0, The weight may range from 0 to 2^32-1). - * The dApp defines what the weight means. - * Other than validating it is in-range no further validation is done at the base registration level. - * For example: - * Project Catalyst uses the weight to apportion Voting Power in a delegation registration. - * Another dApp may use the weight to define the relative contribution each Role Key plays in a grouped registration. - * The dApp is responsible for defining what the Weight means for a particular role. - * If all weights are equal and convey no further meaning they can be elided to reduce the - size of the registration metadata. - * A dApp can specify if it is NOT valid to elide the Weight from a weighted role public key list. +The actual set of simple public keys registered is the union set of all simple public keys registered on-chain. +This allows simple public keys to be securely rotated or removed from a registration. -Each dApp defines what is meant by a Role Key List. -They define if the List is weighted or not and how it is to be interpreted, in reference to the Role itself. +CBOR allows elements of an array to be skipped or marked as absent using [CBOR Undefined/Absent Tags]. -##### Simple Role Key List +An element in the array marked "undefined" (`0xf7`) is used to indicate that no change to that array position is to be made. +An element in the array marked "absent" (`0xd8 0x1f 0xf7`) is used to indicate that any key at this position is revoked. -```cbor - [ , , ... ] -``` +Using these two element we can define the array as the union of all arrays and keys can be freely altered or removed. -example: +Examples: -```cbor -[ - h'A71A8700248D4C91E01A2A2CB5F4F0E664F084EB761C6792AEDD28160C1E403C', - h'C606D983C5545800FAF20519D21988AA0A13271BA12BA9A8643FCFAD58697C97' -] +```txt +[Key 1, Key 2, Key 3] + +[undefined, absent, undefined] ``` -##### Weighted Role Key List +would result in: -```cbor - [ - [ , ], - [ , ], - ... - ] +```txt +[Key 1, undefined, Key 3] ``` -example: +If this was followed with: -```cbor -[ - [h'A71A8700248D4C91E01A2A2CB5F4F0E664F084EB761C6792AEDD28160C1E403C', 25], - [h'C606D983C5545800FAF20519D21988AA0A13271BA12BA9A8643FCFAD58697C97', 75] -] +```txt +[undefined, undefined, undefined, undefined, Key 5] ``` -#### Tooling - -Supporting tooling should clearly define and differentiate this as a unique key type, describing such keys as "CIP-xx role keys". -When utilizing Bech32 encoding the appropriate `role_sk` and `role_vk` prefixes should be used as described in [CIP-05](https://github.com/cardano-foundation/CIPs/tree/master/CIP-0005) - -Examples of acceptable `keyType`s for supporting tools: - -| `keyType` | Description | -| --------- | ----------- | -| `CIP36RoleSigningKey_ed25519` | CIPxx Role Signing Key | -| `CIP36RoleVerificationKey_ed25519` | CIPxx Role Verification Key | +we would then have the resultant set of keys: -### SubKey 2 - Stake Public Key - -This is represented as a CBOR Byte-string, 32 bytes long. - -This is the actual [ED25519-BIP32] Stake Public key of the wallet, and NOT the stake key public hash. -This is the primary key associating the users wallet with their role key. -How the dApp uses this information is dApp specific. -For example Project Catalyst can use this information to derive voting power for a voter role. - -It is an ed25519 public key, and is represented as a byte-string 32 bytes in length. - Example: - -```cbor -#6.32773(h'ad4b948699193634a39dd56f779a2951a24779ad52aa7916f6912b8ec4702cee') +```txt +[Key 1, undefined, Key 3, undefined, Key 5] ``` -Note: There can only be a single Stake Public Key in the registration. -Multiple Stake Public Keys can be associated with the same Role Key/s, however there needs to be one registration per stake address. - -### SubKey 3 - Payment Address (OPTIONAL) +The latest key set is what is currently active for the role. -This is represented as a CBOR Byte-string, Between 29 and 57 bytes long (inclusive). +These keys are usable to sign data for a role, but are not a replacement for certificates, and some roles may not allow their use. -If Present, this is a Shelley payment address as defined by [CIP-0019]. -If must be discriminated for the same network this transaction is submitted to. -Its purpose is to enable a role registration to receive rewards. -How or what rewards can be earned are outside the scope of this CIP. +### Certificate Revocation List -For CIP-15 compatibility ONLY, in a CIP-15 format registration, a Stake Reward Address may also be present in Subkey 3. +The certificate revocation list is used by an `issuer` of a certificate to revoke any certificate they have issued. +The certificate is considered revoked as soon as it appears in the revocation list. +If a self signed certificate is to be rolled, a registration will revoke the previously self signed certificate and +simultaneously register a new certificate. -This Subkey is optional, because not all roles will need or offer the ability to be earn rewards for the role. -In these cases, the payment address is redundant. -The dApp defines if this field is required or not for a particular role, and that is outside the scope of this CIP. +This ensures that the roles registered always have a valid certificate and allows registration to be dynamically updated. -### SubKey 4 - Nonce +The revocation list is simply a list of blake2b-128 hashes of the certificate/s to be revoked. +Note, as stated above the only party that can revoke a certificate is the issuer, so the metadata must be posted by the issuer using +their own role 0 key. -The `nonce` is an unsigned integer (of CBOR major type 0). +Any certificate that is revoked which was used to issue other certificates results in ALL certificates issued by the +revoked certificate also being revoked. -It SHOULD be monotonically rising across all transactions with the same staking key. -A simple way to ensure the `nonce` is monotonically increasing, without reference to the previous `nonce` is to use the the current slot number, at the time the transaction is created. +### Role definitions -The `nonce` is specific to the dAPP UUID and Purpose. -The greatest `nonce` for any particular `dApp UUID` + `purpose` is the latest registration transaction, regardless of the order they are seen on the blockchain itself. +Roles are defined in a list. +A user can register for any available role, and they can enrol in more than one role in a single registration transaction. -For example, given the following transactions for the same Stake Address: +The validity of the registration is as per the rules for roles defined by the dApp itself. -| Slot No | Purpose | UUID | Nonce | -| --- | --- | --- | --- | -| 6128480 | 0 | h'ca7a195772774f8884dd5990f4c2ef95' | 6128420 | -| 6128500 | 0 | h'ca7a195772774f8884dd5990f4c2ef95' | 6128400 | -| 6128520 | 0 | h'ca7a195772774f8884dd5990f4c2ef95' | 6128380 | +Role registration data is further divided into: -The transaction in the earlier slot# 6128480 would be the latest of these 3 registrations, because it has the highest `nonce`. - This can occur because it is possible for transactions in a small window of time to be added to a block in a different sequence to the one they were posted in. +1. [A Role number](#role-number) +2. An Optional reference to the roles signing key +3. An Optional reference to the roles encryption key +4. An optional reference to the on-chain payment key to use for the role. +5. And an optional dApp defined set of role specific data. -The `nonce` when used correctly, therefore unambiguously defines the chronological order of the transactions. +#### Role Number -In the event that a `nonce` is exactly the same in two or more registrations for the same dApp UUID/Purpose, then the chronological order they appear in the blockchain determines which of the ambiguous `nonce` are the latest, for example: +All roles, except for Role 0, are defined by the dApp. -| Slot No | Purpose | UUID | Nonce | -| --- | --- | --- | --- | -| 6128480 | 0 | h'ca7a195772774f8884dd5990f4c2ef95' | 6128420 | -| 6128500 | 0 | h'ca7a195772774f8884dd5990f4c2ef95' | 6128420 | -| 6128520 | 0 | h'ca7a195772774f8884dd5990f4c2ef95' | 6128420 | +Role 0 is the primary role and is used to sign the metadata. +All compliant implementations of this specification use Role 0 in this way. -The registration in Slot No 6128520 is the latest registration, because the `nonce` is unable to unambiguously define the chronological order the transactions were posted. +#### Reference to a role signing key -The dApp defines for every purpose what a `later` vs `older` registration means. -It is common that a later `nonce` obsoletes an earlier registration for the same purpose. +Each role can optionally be used to sign data. +If the role is intended to sign data, the key it uses to sign must be declared in this field. +This is a reference to either a registered certificate for the identity posting the registration, +or one of the defined simple public keys. -The full definition of registration validity and priority with respect to chronology of the transactions is outside the scope of this CIP and must be defined by every dApp which implements this specification. +A dApp can define is roles allow the use of certificates, or simple public keys, or both. -### SubKey 5 - Purpose +Role 0 MUST have a signing key, and it must be a certificate. -The `purpose` is an unsigned integer (of CBOR major type 0). - -Purpose defines the PURPOSE the registration transaction is for. -The dApp can define any number of purposes, and their definition is outside the scope of this specification. - -The combination of a [dApp UUID][dApp-UUID] and Purpose defines a specific role registration for a dApp.7 - -For example, in Project Catalyst Purpose 0 defines a Voter registration. - -This specification is not limited to this definition for Purpose 0, and any other dApp may assign a different Purpose to Purpose 0, within its unique [dApp UUID][dApp-UUID]. - -### SubKey 6 - dApp UUID - -This is represented as a CBOR Byte-string, 16 bytes long. - -Each dApp that uses this specification MUST define a [Random V4 UUID](https://www.rfc-editor.org/rfc/rfc4122). -Other UUID version types are invalid. -Nil or MAX UUID V4 are also invalid and must not be used. -The Random UUID must be properly generated using a good quality RNG. - -Briefly, the Display Format of a Valid V4 UUID is: - -```uuid -xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx -``` - -y has the bit pattern [10xxxxxx]. - -All `x` Bytes/Bits are randomly determined. - -However, in the registration transaction it is always represented in its compact format of 128 bits (16 bytes). - -It is recommended that dApps register their self allocated UUID in the following table. - -UUID Registration: -| `UUID` | dApp Assigned | CIP Defining Roles | -| --------- | ----------- | --- | -| `ca7a1957-7277-4f88-84dd-5990f4c2ef95` | Project Catalyst UUID | CIP-62 | - -However as the chance of a collision if a Random UUID is highly unlikely (103 Trillion Properly generated v4 UUID's have a 1 in 1 billion chance of collision.) this is not a requirement. - -It is in the dApp implementors self interest to generate a good quality UUID to allow them to correctly distinguish their registrations vs those of another application. - -### SubKey 7 - Expires (Optional) - -The Expiry is represented by an unsigned integer (of CBOR major type 0) a maximum of 64 bits in size. - -If the Expires sub key is not present, it defaults to 0. -The Expires subkey set to 0 = DO NOT EXPIRE. - -Any other value defines the time, as an integer number of seconds since 1/1/1970 UTC. -Otherwise known as Unix Epoch time. -When the Unix Epoch time exceeds the Expires time, the registration should be considered obsolete or invalid. - -For example an expires time of 1688169600 will be considered expired only after Saturday, July 1, 2023 0:00:00 UTC. - -This allows dApps and Role registrations to be bounded by the creator of the registration ONLY. - -Individual dApps will specify how exceeding Unix Epoch time effects the registration. -The dApp may define that expiry is not available, in which case this field will have no effect. -However, if it is supported by the dApp, it must be interpreted as defined here. - -The dApp is also free to apply other "expiry" conditions to old registrations, and they are outside the scope of this specification. -For example, a dApp may reject or ignore all registrations that were placed on chain more than 6 months before they are used, regardless of the setting of `expires`. - -### SubKey 8-99 - Reserved - -These subkeys are reserved and may not be used by a dApp that conforms to this specification. -If these keys are defined at a later date, they will de defined ina CIP which either updates or obsoletes this specification. - -Any dApp which uses Subkeys 8-99 violates this CIP and is non-conformant. -However, a wallet should not reject the creation of a registration that violates this rule, to allow for future upgrades or amendments to the specification without necessitating tooling changes to support them. +A reference to a key/certificate can be a cert in the same registration, or any previous registration. +If the certificate is revoked, the role is unusable for signing unless and until a new signing certificate +is registered for the role. ### SubKey 100+ - dApp Defined Extended Metadata @@ -576,24 +313,12 @@ This is because definition of this metadata is intentionally fluid to allow the ### High level overview of the Role Registration witness data ## Rationale: how does this CIP achieve its goals? - ## Path to Active ### Acceptance Criteria - ### Implementation Plan - ## References @@ -607,5 +332,5 @@ Code samples and reference material are licensed under [Apache 2.0] [Apache 2.0]: https://www.apache.org/licenses/LICENSE-2.0.html [CBOR]: https://www.rfc-editor.org/rfc/rfc8949.html [CBOR - Core Deterministic Encoding Requirements]: https://www.rfc-editor.org/rfc/rfc8949.html#section-4.2.1 -[CIP0003]: https://cips.cardano.org/cip/CIP-0003 [C509]: https://datatracker.ietf.org/doc/html/draft-ietf-cose-cbor-encoded-cert-07 +[CBOR Undefined/Absent Tags]: https://github.com/svaarala/cbor-specs/blob/master/cbor-absent-tag.rst diff --git a/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/images/x509-roles.d2 b/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/images/x509-roles.d2 new file mode 100644 index 00000000000..dd844049df0 --- /dev/null +++ b/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/images/x509-roles.d2 @@ -0,0 +1,49 @@ +vars: { + d2-config: { + layout-engine: elk + + # Terminal theme code + theme-id: 300 + } +} + +classes: { + NONE: {style.opacity: 0} + RBAC_TABLE: { + shape: sql_table + style: { + border-radius: 15 + } + } +} + +title: |md + # x509 RBAC Metadata +| { + shape: text + near: top-center + style: { + font-size: 25 + } +} + +a_block: "" { + rbac: "x509 Role based Access Control" { + class: RBAC_TABLE + ? 10=x509 certs: "[ + DER Certs ]" + ? 20=c509 certs: "[ + CBOR Certs ]" + ? 30=public keys: "[ + Public Keys ]" + ? 40=revocation set: "[ + Revoked Cert hash]" + "? 100=Role Data Set": "[ + Role Data ]" + } + + role_data: "Role Data" { + class: RBAC_TABLE + 0=role number: "uint" + ? 1=role-signing-key: "Key Reference" + ? 2=role-encryption-key: "Key Reference" + ? 3=payment-key: "OnChain Payment Key Reference" + ? 10-99=Role Specific Data: "Variable per Role" + } + rbac."? 100=Role Data Set" -> role_data +} diff --git a/docs/src/catalyst-standards/draft-cips/images/x509-roles.svg b/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/images/x509-roles.svg similarity index 50% rename from docs/src/catalyst-standards/draft-cips/images/x509-roles.svg rename to docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/images/x509-roles.svg index 587bbf3cf80..c2da010a551 100644 --- a/docs/src/catalyst-standards/draft-cips/images/x509-roles.svg +++ b/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/images/x509-roles.svg @@ -1,13 +1,13 @@ -

x509 RBAC Metadata

-
 x509 Role based Access Control? 10=x509 certs[ + DER Certs ]? 20=c509 certs[ + CBOR Certs ]? 30=public keys[ + Public Keys ]? 40=revocation set[ + Revoked Cert hash]? 50=DiDDiD???? 51=Verifiable Credentials[ + VC??? ]? 100=Role Data Set[ + Role Data ] Role Data0=role numberuint? 1=role-signing-keyKey Reference? 2=role-encryption-keyKey Reference? 3=payment-keyOnChain Payment Key Reference? 10-99=Role Specific DataVariable per Role - - +

x509 RBAC Metadata

+
 x509 Role based Access Control? 10=x509 certs[ + DER Certs ]? 20=c509 certs[ + CBOR Certs ]? 30=public keys[ + Public Keys ]? 40=revocation set[ + Revoked Cert hash]? 100=Role Data Set[ + Role Data ] Role Data0=role numberuint? 1=role-signing-keyKey Reference? 2=role-encryption-keyKey Reference? 3=payment-keyOnChain Payment Key Reference? 10-99=Role Specific DataVariable per Role + + diff --git a/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/x509-roles.cddl b/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/x509-roles.cddl index e0013a2004e..ceea0809365 100644 --- a/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/x509-roles.cddl +++ b/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/x509-roles.cddl @@ -20,8 +20,6 @@ x509-roles-v0-body = { ? c509-certs => [ + c509_cert ], ? pub-keys => [ + simple-public-key-type ], ? revocation-list => [ + revocation-set ], - ? attached-did => dids, - ? attached-vc => vcs, ? role-set => role-data-set, ? purpose-key-set => purpose-data-set, } @@ -40,9 +38,17 @@ c509_cert = bytes .cbor any; A CBOR Encoded C.509 Certificate (binary) simple-public-keys = 30 ; Simple Public Keys simple-public-key-type = $simple-public-key-types -$simple-public-key-types /= ed25519-public-key +$simple-public-key-types /= undefined_key ; Key not defined in this array (use any previous definition) +$simple-public-key-types /= deleted_key ; Key is to be deleted in any previously defined for this position. +$simple-public-key-types /= ed25519-public-key ; ED25519 Public Key + +; Currently supported simple public key types ed25519-public-key = #6.32773(bstr .size 32) ; Simple public keys must be tagged to identify their type. +; These entries come from https://github.com/svaarala/cbor-specs/blob/master/cbor-absent-tag.rst +undefined_key = undefined ; No change to the key in this position of the array +deleted_key = #6.31(undefined) ; delete the key (if any) at this position of the array + ; x509/c509/simple key Revocation Lists ; Keys can only be revoked by the owner of the key or any issuer CA in the chain. ; Revocation becomes active AFTER certs in the same transaction are processed. @@ -50,14 +56,6 @@ revocation-list = 40 ; Revocation List revocation-entry = bytes .size 16; A blake2b-128 hash of the certificate/public key to be revoked revocation-set = [ + revocation-entry ] -; Digitial ID and Verifiable Credentials attached to this registration. - -attached-did = 50 ; DID/s attached to the certificates/on-chain identity -attached-vc = 51 ; Verifiable Credentials attached to the certificates/on-chain identity - -dids = [ + bytes ] ; One or multiple DIDs -vcs = [ + bytes ] ; One or multiple Verifiable Credentials - ; Role Registrations role-set = 100 @@ -120,4 +118,4 @@ first-purpose-key = 200 last-purpose-key = 299 purpose-data-set = any -; Note: any individual error in the role registration invalidates the entire registration. \ No newline at end of file +; Note: any individual error in the role registration invalidates the entire registration. From 29042275038523b04d0d024c8fd681c690b07509 Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Wed, 10 Apr 2024 10:21:21 +0700 Subject: [PATCH 52/66] fix(cips): rename RBAC definition CIP draft so its easier to identify --- .../x509-role-registration-metadata/{cip-xxxx.md => cip-509B.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/{cip-xxxx.md => cip-509B.md} (100%) diff --git a/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/cip-xxxx.md b/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/cip-509B.md similarity index 100% rename from docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/cip-xxxx.md rename to docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/cip-509B.md From 29fe657f79ba161182bf45fe49bcfb1e2341e7cb Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Wed, 10 Apr 2024 15:53:56 +0700 Subject: [PATCH 53/66] docs(cips): x509 certificate registration format fully defined --- .../x509-envelope-metadata/x509-envelope.cddl | 9 +- .../cip-509B.md | 192 ++++++++++++++++-- .../x509-roles.cddl | 36 +++- 3 files changed, 210 insertions(+), 27 deletions(-) diff --git a/docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/x509-envelope.cddl b/docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/x509-envelope.cddl index ff6b0abc292..759b43597d4 100644 --- a/docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/x509-envelope.cddl +++ b/docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/x509-envelope.cddl @@ -21,11 +21,15 @@ x509_envelope = $x509_envelope .within transaction_metadatum $x509_envelope /= { 0: purpose, ; What purpose does this metadata serve. 1: tx_inputs_hash, ; A hash of the `transaction inputs` field from the transaction the metadata is posted with. - ?2: previous_transaction_id ; Previous transaction ID in the chain of registration updates for this user. - ? chunk_type => [ + x509_chunk ] ; Chunked x509 role registration data. + ? 2: previous_transaction_id ; Previous transaction ID in the chain of registration updates for this user. + chunk_type => [ + x509_chunk ] ; Chunked x509 role registration data. 99: validation_signature ; The signature of the x509 envelope plus all other auxiliary data. } +; When a Role 0 certificate is replaced, the transaction MUST be signed by the previous certificate beign revoked +; As well as the new certificate that is replacing it. +certificate_replacement_signature = [ old: validation_signature, new: validation_signature ] + ; hash of the previous transaction in the registration chain. ; There can only be one registration for a user for a purpose that does not have a previous transaction id. ; This would be the first. @@ -43,6 +47,7 @@ $hash32 /= bytes .size 32 ; However an application could choose to implement no compression or only one of either brotli/zstd. ; Chunk Types - Allows to identify how the chunk data is compressed to save on-chain space. + chunk_types = ( raw: 10 ; Data is just chunked, not compressed (raw) brotli: 11 ; Data is compressed with BROTLI and then chunked. diff --git a/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/cip-509B.md b/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/cip-509B.md index 868b488bddc..c856ab41e11 100644 --- a/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/cip-509B.md +++ b/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/cip-509B.md @@ -166,7 +166,8 @@ At a high level, Role registration will collect the following data: 2. An [optional list](#x509-certificate-lists) of [CBOR Encoded X.509 Certificates][C509] 3. An [optional list](#simple-public-keys) list of tagged simple public keys. 4. An [optional certificate revocation](#certificate-revocation-list) set. -5. An optional set of role registration data. +5. An [optional set](#role-definitions) of role registration data. +6. An [optional list] of purpose specific data. ### x509 Certificate Lists @@ -193,6 +194,26 @@ By including the Signature in the transaction, we are able to make a verifiable off-chain certificate and the on-chain identity. This can not be forged. +#### Plutus access to x509 certificates + +Plutus is currently incapable of reading any metadata attached to a transaction. +This specification allows for C509 encoded certificates to be present in the datum output of the transaction itself. +Any C509 certificates present in the metadatum of the transaction are considered to be part of the C509 +certificate list for the purposes of this specification. + +A C509 certificate in a metadatum that is to be included in the registration MUST be included in the C509 certificate list +as a reference. + +The reference defines the metadatum the C509 certificate can be found in the transaction, +and the offset in that metadatum where the certificate is located. +The Certificates MUST be in the same transaction as the Metadatum, it is not possible to refer to a certificate +embedded in metadatum in another transaction. + +Certificates in metadatum that are not linked in this way are ignored for the purpose of this specification. + +Transaction outputs at key 1 of the transaction can contain any number of arrays of certificates. +This is only limited by the transaction itself. + ### Simple Public Keys Rather than require full certificates, dApps can use simple public keys. @@ -266,18 +287,26 @@ The validity of the registration is as per the rules for roles defined by the dA Role registration data is further divided into: 1. [A Role number](#role-number) -2. An Optional reference to the roles signing key -3. An Optional reference to the roles encryption key -4. An optional reference to the on-chain payment key to use for the role. -5. And an optional dApp defined set of role specific data. +2. An [Optional reference](#reference-to-a-role-signing-key) to the roles signing key +3. An [Optional reference](#reference-to-a-role-encryption-key) to the roles encryption key +4. An [optional reference](#on-chain-payment-key-reference) to the on-chain payment key to use for the role. +5. And [an optional](#role-extended-data-keys) dApp defined set of role specific data. #### Role Number All roles, except for Role 0, are defined by the dApp. -Role 0 is the primary role and is used to sign the metadata. +Role 0 is the primary role and is used to sign the metadata and declare on-chain/off-chain identity linkage. All compliant implementations of this specification use Role 0 in this way. +dApps can extend what other use cases Role 0 has, but it will always be used to secure the Role registrations. + +For example, in Catalyst Role 0 is a basic voters role. +Voters do not need to register for any other role to have basic interaction with project Catalyst. + +The recommendation is that Role 0 be used by dApps to give the minimum level of access the dApp requires and +other extended roles are defined as Role 1+. + #### Reference to a role signing key Each role can optionally be used to sign data. @@ -288,40 +317,167 @@ or one of the defined simple public keys. A dApp can define is roles allow the use of certificates, or simple public keys, or both. Role 0 MUST have a signing key, and it must be a certificate. +Simple keys can not be used for signing against Role 0. + +The reason for this is the Role 0 certificate MUST include a reference to the on-chain identity/s to be bound to the registration. +Simple public keys can not contain this reference, which is why they are not permissible for Role 0 keys. A reference to a key/certificate can be a cert in the same registration, or any previous registration. If the certificate is revoked, the role is unusable for signing unless and until a new signing certificate is registered for the role. -### SubKey 100+ - dApp Defined Extended Metadata +#### Reference to a role encryption key + +A Role may require the ability to transfer encrypted data. +The registration can include the Public key use by the role to encrypt the roles data. +Due to the way public key encryption works, this key can only be used to send encrypted data to the holder of the public key. +However, when two users have registered public keys, +they can use them off-chain to perform key exchange and communicate privately between themselves. + +The Role encryption key must be a reference to a key that supports public key encryption, and not just a signing key. +If the key referenced does not support public key encryption, the registration is invalid. + +#### On-chain payment key reference + +Some dApps may require a user to register their payment key, so that they can be sent rewards, +or native tokens or nft's or for other use cases. + +Registrations like CIP-15/36 for catalyst include a payment key. +However, a fundamental problem with these metadata standards is there is no way to validate: + +1. The payment key declared is valid and capable of receiving payments. +2. That the entity posting the registration actually owns the payment key registered. + +It is important that payment keys be verifiable and provably owned to the registrar. + +A Payment key reference in this CIP solves this problem by only allowing a reference to either a transaction input or output. + +The reference is a simple signed integer. +If the integer is positive, then it is referencing the spent UTXO in the transaction Input at the same offset. +Because its is required to prove one can spend a UTXO to post the transaction, +the transaction itself proves that the Payment address being registered is both valid and owned by the registrar. + +If the reference is negative, then the payment key references a transaction output. +The value is negated to get the offset into the transaction output array. + +If the transaction output address IS also an input to the transaction, +then the same proof has already been attached to the transaction. + +However, if the transaction output is not also an input, the transaction MUST include the output address +in the required signers field, and the transaction must carry a witness proving the payment key is owned. + +This provides guarantees that the entity posting the registration has posted a valid payment address, and that they control it. + +If a payment address is not able to be validated, then the entire registration metadata is invalid. + +#### Role extended data keys -Subkeys 100+ are available for dApp authors to add further metadata to registrations under this CIP. -The dApp author should clearly document what this metadata is, how it is represented and formatted. +Each dApp can declare that roles can have either mandatory or optional data items that can be posted with any role registration. -It is valid for different extended metadata to be defined for different purposes for the same [dApp UUID][dApp-UUID]. +Each role can have a different set of defined role registration data. +It is not required that all roles have the same data. -Examples of extended metadata: +As the role data is dApp specific, it is not detailed here. +Each dApp will need to produce a specification of what role specific data it requires, and how it is validated. -* Social Media contacts for a particular role. -* A Description of the person or group covered by the registration. -* Links to other systems with expanded information related to the registration. +### dApp specific registration data -The wallet when signing these registration transactions should not validate this metadata strictly. -If the wallet believes it is invalid, it can warn the user, but should still allow it to be signed. -This is because definition of this metadata is intentionally fluid to allow the dApp authors to add or remove optional metadata, and this should be able to occur without breaking supporting tooling. +Each dApp can define data which is required for registration to the dApp. +This data can be defined as required or optional by the dApp. -### High level overview of the Role Registration witness data +The data is global and applies to all roles registered by the same identity. + +This can include information such as ADA Handles, or reputation data associated with a registration. + +As this data is dApp specific it is not detailed here. + +### Registration validity + +Any registration metadata must be 100% valid, or the entire registration data set is rejected as invalid. + +For example, if three roles were registered, Role 0, 1 and 2. + +Role 0 is perfectly fine, as is Role 1. +However Role 2 has an error with the payment key. +None of the role registrations will take effect. + +### Optional fields + +As role registration is cumulative and each new registration for an entity on a dApp simply updates a previous +registration, then all fields are optional. + +The individual posting the registration need ONLY post the data that has changed or is being added. +This is intended to minimize the amount of on-chain data. +It does mean that a registration state can only be known by collecting all registration for an individual from the chain. + +### First Registration + +The very first registration must have the following features: + +1. It MUST have a certificate that is appropriately issued (either self signed or issued by a trusted CA). + 1. The certificate requirement is defined by each dApp. + 2. The certificate MUST link to at least 1 on-chain identity. + dApps define what the required identities are. + It is valid for a dApp to require multiple on-chain identities to be referenced. + However, general validity can be inferred by the presence or lack of a referenced on-chain identity. + 1. Either currently a Stake Address; or + 2. Another on-chain identity key (such as dRep). + 3. The transaction MUST be witnessed by ALL the Role 0 referenced on-chain identities. + 1. If the address is not a natural address to witness the transaction, it MUST be included in the + required signers field of the transaction. + And it must appear in the witness set. +2. It MUST have a Role 0 defined, that references the certificate. +3. It must be signed by the Role 0 certificate. + +Once the Role 0 certificate is registered, the entity is registered for the dApp. +Provided the dApp will accept the individuals registration. + +Other certificates DO NOT need to have references to the on-chain identity of the user. +However, if they do, they must be witnessed in the transaction to prove they are validly held and referenced. + +### Deregistering + +Once a user has registered for Role 0, the only way they can de-register is to revoke their Role 0 key. +If the Role 0 key is revoked, and is not replaced in the same transaction with a new key, then all +registration data for that user is revoked. + +A user could then create a new registration with a new Role 0 certificate, +but they would also need to register for any Roles again. + +This is because if the Role 0 certificate is not immediately rolled over, then all role registrations are deemed terminated. + +It is also possible for a de-registration to cause a linked registration to use a new on-chain identity. + +For example, if the current Role 0 registration referenced Stake address 123, +and a new registration is posted that revokes the old cert, and posts a new cert referencing Stake address 456, +then the on-chain stake address identity will have changed from 123 to 456. + +Note: in the case of a CA revoked certificate, +the subject must have registered a new Role 0 certificate before the issuer revokes it. + +Otherwise, they will become de-registered when the issuer revokes their certificate, and they must then completely re-register. ## Rationale: how does this CIP achieve its goals? ## Path to Active +* All related CIP's are implemented in a MVP implementation for Project Catalyst. +* All implementation details have been refined allowing unambiguous implementation for the MVP. +* Appropriate community driven feedback has occurred to allow the specification to mature. + ### Acceptance Criteria ### Implementation Plan ## References +* [CC-BY-4.0] +* [Apache 2.0] +* [CBOR] +* [CBOR - Core Deterministic Encoding Requirements] +* [C509] +* [CBOR Undefined/Absent Tags] + ## Copyright This CIP is licensed under [CC-BY-4.0] diff --git a/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/x509-roles.cddl b/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/x509-roles.cddl index ceea0809365..2a7ee4267f9 100644 --- a/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/x509-roles.cddl +++ b/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/x509-roles.cddl @@ -16,12 +16,12 @@ $x509_roles /= x509-roles-v0 x509-roles-v0 = [ 0, x509-roles-v0-body ] x509-roles-v0-body = { - ? x509-certs => [ + x509_der_cert ], - ? c509-certs => [ + c509_cert ], - ? pub-keys => [ + simple-public-key-type ], - ? revocation-list => [ + revocation-set ], - ? role-set => role-data-set, - ? purpose-key-set => purpose-data-set, + ? x509-certs => [ + x509_der_cert ], ; Unordered List of DER encoded x509 certificates + ? c509-certs => [ + c509_cert ], ; Unordewed List of CBOR encoded C509 certificates (or metadatum references) + ? pub-keys => [ + simple-public-key-type ], ; Ordered list of simple public keys that are registered. + ? revocation-list => [ + revocation-set ], ; Revocation list of certs being revoked by an issuer. + ? role-set => role-data-set, ; Set of role registration data + ? purpose-key-set => purpose-data-set, ; Set of purpose specific data to be registered. } ; x509 Certificates @@ -30,7 +30,29 @@ x509_der_cert = bytes ; A DER Encoded X.509 Certificate (binary) ; c509 Certificates c509-certs = 20 ; Unorderd bag of C509 CBOR Encoded certificates -c509_cert = bytes .cbor any; A CBOR Encoded C.509 Certificate (binary) +c509_cert = ( + C509CertInMetadatumReference / ; A reference to a certificate encoded in a metadatum + C509Certificate ; An actual certificate. +) + +; C509 Certificate from https://datatracker.ietf.org/doc/draft-ietf-cose-cbor-encoded-cert/09/ +C509Certificate = [ + TBSCertificate: bytes .cbor any, ; A CBOR Encoded C.509 Certificate (binary) issuerSignatureValue: any, ; The issuers signature (dependent on the signature algorithm used by the certificate)] + +; A reference to a C509 certificate held in a metadatum. +; if there are multiple transaction outputs that contain certificates they need to be listed individually. +C509CertInMetadatumReference = [ + txn_output_field: uint, ; Currently this is always 1. It references the key of the transaction outputs to use from the transaction. + txn_output_index: uint, ; The specific transaction output to use in the list of transaction outputs. + cert_ref: C509CertInMetadatumReferenceOffset ; Reference to the certificates in the metadatum. +] + +; Which certificate/s to reference +C509CertInMetadatumReferenceOffset = ( + null // ; Reference is a single cert, or an array of certs, include them all, in order listed. + uint // ; Reference a single cert at this offset in a CBOR array, or at this key in a CBOR map. + [ + uint ] ; Reference multiple certs at these offsets in a CBOR array, or at these keys in a CBOR map, in the order listed. +) ; Simple Public Keys ; These are just signing keys of the specified type, and are not true certs From daf0b0ee4b85dcff51f5f76f9ac454ba2a0df4e0 Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Wed, 10 Apr 2024 16:02:55 +0700 Subject: [PATCH 54/66] docs(cips): Document the restricted plutus subset. --- .../cip-509C.md | 57 +++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 docs/src/catalyst-standards/draft-cips/c509-plutus-restricted-certificate/cip-509C.md diff --git a/docs/src/catalyst-standards/draft-cips/c509-plutus-restricted-certificate/cip-509C.md b/docs/src/catalyst-standards/draft-cips/c509-plutus-restricted-certificate/cip-509C.md new file mode 100644 index 00000000000..698044be7c8 --- /dev/null +++ b/docs/src/catalyst-standards/draft-cips/c509-plutus-restricted-certificate/cip-509C.md @@ -0,0 +1,57 @@ +--- +CIP: /? +Title: Restricted format for C509 compatibility with Plutus +Category: MetaData +Status: Proposed +Authors: + - Steven Johnson +Implementors: [] +Discussions: + - https://github.com/cardano-foundation/cips/pulls/? +Created: 2023-10-24 +License: CC-BY-4.0 +--- + +## Abstract + +Plutus can access metadatums that encode C509 certificates. +This specification documents the restricted feature set of those certificates. + +## Motivation: why is this CIP necessary? + +In order to keep complexity low, this specification details a set of restriction +on-top of a standard C509 certificate definition. +These restrictions help plutus support the important features of +x509 certificates in smart contracts on-chain. + +They also help reduce the amount of data stored on-chain. + +## Specification + +See [c509-cert-plutus-restricted.cddl](./c509-cert-plutus-restricted.cddl). +This is the formal specification which describes the requirements of on-chain x509 certificates. +ust include a CDDL schema in it's specification.--> + +## Rationale: how does this CIP achieve its goals? + +By clearly defining the feature set that plutus scripts can accept from C509 certificates it is easier for +script writers and certificate creators to produce interoperable certificates. + +## Path to Active + +This draft CIP requires extensive collaboration with multiple parties in order to arrive at a +correct and viable specification. + +It has been kept deliberately terse in order for that process to be as open and collaborative as possible. + +### Acceptance Criteria + +* General community consensus on the minimum standard needs to be agreed. + +### Implementation Plan + +## Copyright + +This CIP is licensed under [CC-BY-4.0] + +Code samples and reference material are licensed under [Apache 2.0] From 3c3008ff993ab3313726971e2e100d64b186293b Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Wed, 10 Apr 2024 16:34:15 +0700 Subject: [PATCH 55/66] docs(cips): Add document detailing how CIP-30 is used to sign the transaction --- .config/dictionaries/project.dic | 7 +- .../x509-rbac-signing-with-cip30/cip-x509D.md | 131 ++++++++++++++++++ .../x509-rbac-signing-with-cip30/cip-xxxx.md | 77 ---------- .../images/cardano-transaction.d2 | 0 .../images/cardano-transaction.svg | 0 5 files changed, 134 insertions(+), 81 deletions(-) create mode 100644 docs/src/catalyst-standards/draft-cips/x509-rbac-signing-with-cip30/cip-x509D.md delete mode 100644 docs/src/catalyst-standards/draft-cips/x509-rbac-signing-with-cip30/cip-xxxx.md rename docs/src/catalyst-standards/draft-cips/{ => x509-rbac-signing-with-cip30}/images/cardano-transaction.d2 (100%) rename docs/src/catalyst-standards/draft-cips/{ => x509-rbac-signing-with-cip30}/images/cardano-transaction.svg (100%) diff --git a/.config/dictionaries/project.dic b/.config/dictionaries/project.dic index fe2d4b39735..b93d260be5d 100644 --- a/.config/dictionaries/project.dic +++ b/.config/dictionaries/project.dic @@ -23,6 +23,7 @@ cfbundle chromedriver chrono ciphertext +CIPs COCOAPODS codegen codepoints @@ -45,7 +46,6 @@ earthfile Edgedriver encryptor endfunction -endfunction fetchval fmtchk fmtfix @@ -83,6 +83,7 @@ localizable loguru mdlint metadatum +metamap mgrybyk mithril mitigations @@ -117,6 +118,7 @@ pytest rapidoc redoc Replayability +repr reqwest rfwtxt ripgrep @@ -169,6 +171,3 @@ xctest xctestrun xcworkspace yoroi -cbor -metamap -repr \ No newline at end of file diff --git a/docs/src/catalyst-standards/draft-cips/x509-rbac-signing-with-cip30/cip-x509D.md b/docs/src/catalyst-standards/draft-cips/x509-rbac-signing-with-cip30/cip-x509D.md new file mode 100644 index 00000000000..232c5c476c6 --- /dev/null +++ b/docs/src/catalyst-standards/draft-cips/x509-rbac-signing-with-cip30/cip-x509D.md @@ -0,0 +1,131 @@ +--- +CIP: /? +Title: Preparing and Signing x509 Metadata +Category: MetaData +Status: Proposed +Authors: + - Steven Johnson +Implementors: [] +Discussions: + - https://github.com/cardano-foundation/cips/pulls/? +Created: 2023-10-24 +License: CC-BY-4.0 +--- + + +# Role Based Access Control Registration + +## Abstract + +This document defines how a dApp will use the wallet connect interfaces of CIP-30 to produce and sign +x509 registration transactions. + +## Motivation: why is this CIP necessary? + +The x509 certificate metadata CIPs are complex, and it is required to clearly document how they +can be produced using standard tooling. + +The primary motivation is that the registration can be produced with existing interfaces. + +Wallets MAY OPTIONALLY detect this registration format and display it in a more meaningful way to users. +But that is not required. + +The aim is to have broad interoperability with ALL wallets that already implement CIP-30. + +## Specification + +### Components of an individual transaction + +![Cardano Transaction Anatomy](./images/cardano-transaction.svg) + +### Creation and Signing procedure + +![Creation/Signing procedure](../x509-envelope-metadata/images/metadata-envelope-process.svg) + +### Wallet interaction + +CIP 30 defines two main functions. + +1. signData +2. signTransaction + +We deliberately do NOT use signData. +The reason is signData has limitations, primarily it can ONLY sign data with a single key. + +it is also incapable of creating data that can not be replayed across transactions, which is a requirement. + +Accordingly, the entire transaction is produced using `signTransaction`. + +Following the procedure described above, the prepared transaction and complete metadata +(which has been pre-signed with the role 0 keys of the user) are sent to the wallet to be signed. + +The Transaction MUST include where appropriate extra keys in `required signers` in the transaction to properly +link the off-chain role keys with on-chain keys. + +The wallet DOES NOT need to know that the metadata has this requirement, it simply sees the keys it needs to witness +the transaction with, and prompts the user to sign. + +#### Enhanced UX + +The Role registration metadata is general in form. + +A Wallet MAY elect to detect that it is signing a role registration and +present the data in a form which is easier for the user to reason through. + +It may also be aware of key supported dApps and provide even further information. +It can also perform both universal and dApp specific validity checks against the registration to ensure +it is properly structured by the dApp. + +However, the Wallet should simply WARN the user if it detects a problem, and not prevent the user from +signing the transaction. + +Once the wallet has signed the transaction, the dApp will have a fully signed role registration transaction and metadata. +It will be impossible for the dApp or anyone else to separate the metadata from the transaction and retain its validity. +It is impossible to replay the metadata on a new transaction and it retain validity. + +With the complete transaction properly signed, it can then be posted on-chain. + +### Posting the transaction + +Once the transaction has been properly constructed and signed, anyone with a copy of it can post it on-chain. + +it is recommended that dApps post the transaction to their own backend logic, which handles posting the data on-chain +vs posting the data on-chain through the wallet. + +The reason for this, is this affords the dApp backend the opportunity to +validate the registration data in its entirety before posting it on-chain. + +It is preferable to inform a user their registration is invalid or has problems +BEFORE they spend the ADA required to post the transaction, +and the only authoritive way this can be achieved is through the dApp. + +having validated the registration would be valid if posted on-chain, it is then posted by the dapp on-chain. + +Once the dApp sees the registration appear in the ledger, +it is now confirmed that not only was the registration valid, but that the transaction itself was valid, +properly spent valid UTXOs, etc. + +The dApp may cache registration data it received from users, +but it should never act on it until it has been seen validly posted on-chain. + +## Rationale: how does this CIP achieve its goals? + +This CIP defines wallet interactions and how CIP-30 is used to create and +post transactions that conform to the x509 metadata specification. + +## Path to Active + +### Acceptance Criteria + +### Implementation Plan + +## References + +## Copyright + +This CIP is licensed under [CC-BY-4.0] + +Code samples and reference material are licensed under [Apache 2.0] + +[CC-BY-4.0]: https://creativecommons.org/licenses/by/4.0/legalcode +[Apache 2.0]: https://www.apache.org/licenses/LICENSE-2.0.html diff --git a/docs/src/catalyst-standards/draft-cips/x509-rbac-signing-with-cip30/cip-xxxx.md b/docs/src/catalyst-standards/draft-cips/x509-rbac-signing-with-cip30/cip-xxxx.md deleted file mode 100644 index 3526b370cda..00000000000 --- a/docs/src/catalyst-standards/draft-cips/x509-rbac-signing-with-cip30/cip-xxxx.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -CIP: /? -Title: Role based Access Control Registration -Category: MetaData -Status: Proposed -Authors: - - Steven Johnson -Implementors: [] -Discussions: - - https://github.com/cardano-foundation/cips/pulls/? -Created: 2023-10-24 -License: CC-BY-4.0 ---- - - - - -# Role Based Access Control Registration - -## Abstract - - -## Motivation: why is this CIP necessary? - - -## Specification - - -## Rationale: how does this CIP achieve its goals? - - -## Path to Active - -### Acceptance Criteria - - -### Implementation Plan - - -## References - -## Copyright - -This CIP is licensed under [CC-BY-4.0] - -Code samples and reference material are licensed under [Apache 2.0] - -[CC-BY-4.0]: https://creativecommons.org/licenses/by/4.0/legalcode -[Apache 2.0]: https://www.apache.org/licenses/LICENSE-2.0.html diff --git a/docs/src/catalyst-standards/draft-cips/images/cardano-transaction.d2 b/docs/src/catalyst-standards/draft-cips/x509-rbac-signing-with-cip30/images/cardano-transaction.d2 similarity index 100% rename from docs/src/catalyst-standards/draft-cips/images/cardano-transaction.d2 rename to docs/src/catalyst-standards/draft-cips/x509-rbac-signing-with-cip30/images/cardano-transaction.d2 diff --git a/docs/src/catalyst-standards/draft-cips/images/cardano-transaction.svg b/docs/src/catalyst-standards/draft-cips/x509-rbac-signing-with-cip30/images/cardano-transaction.svg similarity index 100% rename from docs/src/catalyst-standards/draft-cips/images/cardano-transaction.svg rename to docs/src/catalyst-standards/draft-cips/x509-rbac-signing-with-cip30/images/cardano-transaction.svg From 2b6411f7f90ac3c93898d051d95501e8e4490245 Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Wed, 10 Apr 2024 17:33:47 +0700 Subject: [PATCH 56/66] fix(cips): remove trailing spaces --- .../x509-rbac-signing-with-cip30/cip-x509D.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/src/catalyst-standards/draft-cips/x509-rbac-signing-with-cip30/cip-x509D.md b/docs/src/catalyst-standards/draft-cips/x509-rbac-signing-with-cip30/cip-x509D.md index 232c5c476c6..561d042f0cc 100644 --- a/docs/src/catalyst-standards/draft-cips/x509-rbac-signing-with-cip30/cip-x509D.md +++ b/docs/src/catalyst-standards/draft-cips/x509-rbac-signing-with-cip30/cip-x509D.md @@ -92,25 +92,25 @@ Once the transaction has been properly constructed and signed, anyone with a cop it is recommended that dApps post the transaction to their own backend logic, which handles posting the data on-chain vs posting the data on-chain through the wallet. -The reason for this, is this affords the dApp backend the opportunity to +The reason for this, is this affords the dApp backend the opportunity to validate the registration data in its entirety before posting it on-chain. -It is preferable to inform a user their registration is invalid or has problems -BEFORE they spend the ADA required to post the transaction, +It is preferable to inform a user their registration is invalid or has problems +BEFORE they spend the ADA required to post the transaction, and the only authoritive way this can be achieved is through the dApp. having validated the registration would be valid if posted on-chain, it is then posted by the dapp on-chain. -Once the dApp sees the registration appear in the ledger, -it is now confirmed that not only was the registration valid, but that the transaction itself was valid, +Once the dApp sees the registration appear in the ledger, +it is now confirmed that not only was the registration valid, but that the transaction itself was valid, properly spent valid UTXOs, etc. -The dApp may cache registration data it received from users, +The dApp may cache registration data it received from users, but it should never act on it until it has been seen validly posted on-chain. ## Rationale: how does this CIP achieve its goals? -This CIP defines wallet interactions and how CIP-30 is used to create and +This CIP defines wallet interactions and how CIP-30 is used to create and post transactions that conform to the x509 metadata specification. ## Path to Active From 5f68b88e3c857700efd6309dca070ecf8ac67e1f Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Wed, 10 Apr 2024 17:45:22 +0700 Subject: [PATCH 57/66] fix(cips): Fix line lengths --- docs/src/catalyst-standards/cbor_tags/ulid.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/docs/src/catalyst-standards/cbor_tags/ulid.md b/docs/src/catalyst-standards/cbor_tags/ulid.md index 2ba79b7b635..eda17234842 100644 --- a/docs/src/catalyst-standards/cbor_tags/ulid.md +++ b/docs/src/catalyst-standards/cbor_tags/ulid.md @@ -2,23 +2,23 @@ This document specifies a tag for ULIDs in Concise Binary Object Representation (CBOR) [1]. - Tag: 32770 + Tag: 32780 Data item: byte string Semantics: Binary ULID (https://github.com/ulid/spec/tree/master) Point of contact: Steven Johnson - Description of semantics: https://github.com/input-output-hk/catalyst-voices/tree/main/docs/src/catalyst-standards/cbor_tags/ulid.md + Description of semantics: + https://github.com/input-output-hk/catalyst-voices/tree/main/docs/src/catalyst-standards/cbor_tags/ulid.md ## Semantics -Tag 32770 can be applied to a byte string (major type 2) to indicate that the byte string is a binary [ULID] as specified by the [ULID Binary Layout]. +Tag 32780 can be applied to a byte string (major type 2) to indicate that the byte string +is a binary [ULID] as specified by the [ULID Binary Layout]. ## References -[1] C. -Bormann, and P. -Hoffman. -"Concise Binary Object Representation (CBOR)". -RFC 7049, October 2013. + +[1] [C. Bormann, and P. Hoffman. "Concise Binary Object Representation (CBOR)". RFC 8949, October 2020.][RFC 8949] + [2] [Universally Unique Lexicographically Sortable Identifier][ULID] @@ -26,5 +26,6 @@ RFC 7049, October 2013. Steven Johnson +[RFC 8949]: https://datatracker.ietf.org/doc/html/rfc8949 [ULID]: https://github.com/ulid/spec/blob/master/README.md [ULID Binary Layout]: https://github.com/ulid/spec/tree/master#binary-layout-and-byte-order From 2a9114a66d0aeff1bf91adc2ee9d48b03c945656 Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Wed, 10 Apr 2024 18:06:00 +0700 Subject: [PATCH 58/66] fix(cips): Correct spelling --- .config/dictionaries/project.dic | 5 +++-- cspell.json | 1 + .../c509-cert-plutus-restricted.cddl | 6 ++++-- .../draft-cips/x509-envelope-metadata/cip-509A.md | 2 +- .../x509-envelope-metadata/x509-envelope.cddl | 10 +++++----- .../x509-role-registration-metadata/cip-509B.md | 2 +- .../x509-role-registration-metadata/x509-roles.cddl | 12 ++++++------ 7 files changed, 21 insertions(+), 17 deletions(-) diff --git a/.config/dictionaries/project.dic b/.config/dictionaries/project.dic index f24d4ba871e..f822504d9f3 100644 --- a/.config/dictionaries/project.dic +++ b/.config/dictionaries/project.dic @@ -87,6 +87,7 @@ localizable loguru mdlint metadatum +metadatums metamap mgrybyk mithril @@ -161,10 +162,10 @@ Traceback TXNZD Typer unmanaged -UTXO utxo -Utxos +UTXO utxos +Utxos vite vitss vkey diff --git a/cspell.json b/cspell.json index b729343b8ba..c120639098a 100644 --- a/cspell.json +++ b/cspell.json @@ -175,5 +175,6 @@ "web-components.min.js", "**/generated/**", "utilities/catalyst_voices_remote_widgets/example/**/**", + "**/*.svg" ] } \ No newline at end of file diff --git a/docs/src/catalyst-standards/draft-cips/c509-plutus-restricted-certificate/c509-cert-plutus-restricted.cddl b/docs/src/catalyst-standards/draft-cips/c509-plutus-restricted-certificate/c509-cert-plutus-restricted.cddl index e4fe93fdb16..4967ed331e1 100644 --- a/docs/src/catalyst-standards/draft-cips/c509-plutus-restricted-certificate/c509-cert-plutus-restricted.cddl +++ b/docs/src/catalyst-standards/draft-cips/c509-plutus-restricted-certificate/c509-cert-plutus-restricted.cddl @@ -3,7 +3,9 @@ ; And is restricted/customized to better enable compatibility with Plutus scripts ; that would consume them, without loosing necessary features of x509 ; Not all x509 features are supported and some fields have different semantics to improve -; certificate size and processibility by Plutus Scripts. +; certificate size and ability to be processed by Plutus Scripts. + +; cspell: words reencoded, biguint C509CertificatePlutusRestrictedSubset = [ TBSCertificate, issuerSignatureValue: ed25519Signature, ] @@ -44,7 +46,7 @@ Attribute = ( subjectPublicKey = bytes .size (32..32); Ed25519 public key stored in bytes, adjust size of this if other key types are supported. -; This is a completely custom Attribute for the RelativeDistringuishedName which is only for use with Plutus scripts. +; This is a completely custom Attribute for the RelativeDistinguishedName which is only for use with Plutus scripts. ; attributeType = The type of Cardano key we associate with this certificate. ; proof = Does the transaction require proof that the key is owned by the transaction signer? ; attributeValue = The Cardano public key hash of the attribute type diff --git a/docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/cip-509A.md b/docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/cip-509A.md index 54dac6ddffc..143bd2d645c 100644 --- a/docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/cip-509A.md +++ b/docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/cip-509A.md @@ -103,7 +103,7 @@ any actual role or certificate updates. The data required to register certificates or roles could be large. The [specification for the encoding of all Cardano metadata] also introduces difficulties in encoding x509 certificates. -The contents of the x509 RABC Registration data stored in this key is documented separately. +The contents of the x509 RBAC Registration data stored in this key is documented separately. Its exact contents are not important for this specification except to note, that it will always define at least: * 1 Role 0 signing key MUST always be defined. diff --git a/docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/x509-envelope.cddl b/docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/x509-envelope.cddl index 759b43597d4..03d26d1ddaf 100644 --- a/docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/x509-envelope.cddl +++ b/docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/x509-envelope.cddl @@ -17,7 +17,7 @@ ; The x509 envelope must be valid cardano metadata. x509_envelope = $x509_envelope .within transaction_metadatum -; Strcuture of the x509 envelope itself. +; Structure of the x509 envelope itself. $x509_envelope /= { 0: purpose, ; What purpose does this metadata serve. 1: tx_inputs_hash, ; A hash of the `transaction inputs` field from the transaction the metadata is posted with. @@ -26,21 +26,21 @@ $x509_envelope /= { 99: validation_signature ; The signature of the x509 envelope plus all other auxiliary data. } -; When a Role 0 certificate is replaced, the transaction MUST be signed by the previous certificate beign revoked +; When a Role 0 certificate is replaced, the transaction MUST be signed by the previous certificate being revoked ; As well as the new certificate that is replacing it. certificate_replacement_signature = [ old: validation_signature, new: validation_signature ] ; hash of the previous transaction in the registration chain. ; There can only be one registration for a user for a purpose that does not have a previous transaction id. ; This would be the first. -; Once that is posted, all updates must properly maintian the chain. +; Once that is posted, all updates must properly maintain the chain. ; Dangling registrations for the same purpose are ignored. previous_transaction_id = $hash32 $hash32 /= bytes .size 32 ; x509 Role Registration data is chunked and optionally (preferably) compressed. -; This enables the x509 registration data to have a strucutre not supported by the -; underlying limitions of the on-chain metadatum implementation. +; This enables the x509 registration data to have a structure not supported by the +; underlying limitations of the on-chain metadatum implementation. ; As the x509 registration data may be large, compression is used to minimize on-chain space consumed. ; Best practice would be to compress the data with both brotli and zstd, and only store the ; smallest data set. `raw` storage would only be used if compression did not yield any benefits. diff --git a/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/cip-509B.md b/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/cip-509B.md index c856ab41e11..a0ff97b6513 100644 --- a/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/cip-509B.md +++ b/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/cip-509B.md @@ -435,7 +435,7 @@ Provided the dApp will accept the individuals registration. Other certificates DO NOT need to have references to the on-chain identity of the user. However, if they do, they must be witnessed in the transaction to prove they are validly held and referenced. -### Deregistering +### De-registering Once a user has registered for Role 0, the only way they can de-register is to revoke their Role 0 key. If the Role 0 key is revoked, and is not replaced in the same transaction with a new key, then all diff --git a/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/x509-roles.cddl b/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/x509-roles.cddl index 2a7ee4267f9..47c04265793 100644 --- a/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/x509-roles.cddl +++ b/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/x509-roles.cddl @@ -1,5 +1,5 @@ ; An envelope for Cardano metadata which holds the x509 metadata. -; We do this so that the underlying metadata is not restircted to +; We do this so that the underlying metadata is not restricted to ; Cardano ledger implementation. ; uses @@ -16,8 +16,8 @@ $x509_roles /= x509-roles-v0 x509-roles-v0 = [ 0, x509-roles-v0-body ] x509-roles-v0-body = { - ? x509-certs => [ + x509_der_cert ], ; Unordered List of DER encoded x509 certificates - ? c509-certs => [ + c509_cert ], ; Unordewed List of CBOR encoded C509 certificates (or metadatum references) + ? x509-certs => [ + x509_der_cert ], ; Un-ordered List of DER encoded x509 certificates + ? c509-certs => [ + c509_cert ], ; Un-ordered List of CBOR encoded C509 certificates (or metadatum references) ? pub-keys => [ + simple-public-key-type ], ; Ordered list of simple public keys that are registered. ? revocation-list => [ + revocation-set ], ; Revocation list of certs being revoked by an issuer. ? role-set => role-data-set, ; Set of role registration data @@ -25,11 +25,11 @@ x509-roles-v0-body = { } ; x509 Certificates -x509-certs = 10 ; Unorderd bag of X509 DER Encoded certificates +x509-certs = 10 ; Un-ordered bag of X509 DER Encoded certificates x509_der_cert = bytes ; A DER Encoded X.509 Certificate (binary) ; c509 Certificates -c509-certs = 20 ; Unorderd bag of C509 CBOR Encoded certificates +c509-certs = 20 ; Un-ordered bag of C509 CBOR Encoded certificates c509_cert = ( C509CertInMetadatumReference / ; A reference to a certificate encoded in a metadatum C509Certificate ; An actual certificate. @@ -123,7 +123,7 @@ key-hash = bytes .size 16 ; Reference to a transaction input/output as the payment key to use for a role ; Payment key (n) >= 0 = Use Transaction Input Key offset (n) as the payment key -; Payment key (n) < 0 = Use Transaction Output Key offstet -(n+1) as the payment key +; Payment key (n) < 0 = Use Transaction Output Key offset -(n+1) as the payment key ; IFF a transaction output payment key is defined the payment address must also be in ; the required_signers of the transaction to ensure the payment address is owned and controlled ; by the entity posting the registration. From 51c365efbb6e649bb3b161284d84c47e46605bc8 Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Wed, 10 Apr 2024 18:10:30 +0700 Subject: [PATCH 59/66] fix(cips): spelling --- docs/src/catalyst-standards/cbor_tags/ulid.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/src/catalyst-standards/cbor_tags/ulid.md b/docs/src/catalyst-standards/cbor_tags/ulid.md index eda17234842..5c9ac9b355f 100644 --- a/docs/src/catalyst-standards/cbor_tags/ulid.md +++ b/docs/src/catalyst-standards/cbor_tags/ulid.md @@ -17,6 +17,7 @@ is a binary [ULID] as specified by the [ULID Binary Layout]. ## References + [1] [C. Bormann, and P. Hoffman. "Concise Binary Object Representation (CBOR)". RFC 8949, October 2020.][RFC 8949] From 6312ba7348950a689c83879d13503a27c1d8bfcc Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Wed, 10 Apr 2024 18:36:31 +0700 Subject: [PATCH 60/66] fix(frontend): revert changes to flutter/dart versions --- .../packages/catalyst_voices_assets/example/pubspec.yaml | 2 +- catalyst_voices/packages/catalyst_voices_assets/pubspec.yaml | 2 +- catalyst_voices/packages/catalyst_voices_blocs/pubspec.yaml | 2 +- .../packages/catalyst_voices_localization/pubspec.yaml | 2 +- .../packages/catalyst_voices_repositories/pubspec.yaml | 2 +- .../packages/catalyst_voices_services/pubspec.yaml | 2 +- catalyst_voices/packages/catalyst_voices_shared/pubspec.yaml | 4 ++-- .../packages/catalyst_voices_view_models/pubspec.yaml | 2 +- catalyst_voices/pubspec.yaml | 4 ++-- melos.yaml | 4 ++-- utilities/catalyst_voices_remote_widgets/pubspec.yaml | 2 +- 11 files changed, 14 insertions(+), 14 deletions(-) diff --git a/catalyst_voices/packages/catalyst_voices_assets/example/pubspec.yaml b/catalyst_voices/packages/catalyst_voices_assets/example/pubspec.yaml index 7288ed22e5f..07900cac01c 100644 --- a/catalyst_voices/packages/catalyst_voices_assets/example/pubspec.yaml +++ b/catalyst_voices/packages/catalyst_voices_assets/example/pubspec.yaml @@ -5,7 +5,7 @@ publish_to: none environment: sdk: ">=3.2.6 <4.0.0" - flutter: 3.19.0 + flutter: 3.19.5 dependencies: catalyst_voices_assets: diff --git a/catalyst_voices/packages/catalyst_voices_assets/pubspec.yaml b/catalyst_voices/packages/catalyst_voices_assets/pubspec.yaml index 14a62462651..b658ab5e903 100644 --- a/catalyst_voices/packages/catalyst_voices_assets/pubspec.yaml +++ b/catalyst_voices/packages/catalyst_voices_assets/pubspec.yaml @@ -5,7 +5,7 @@ publish_to: none environment: sdk: ">=3.2.6 <4.0.0" - flutter: 3.19.0 + flutter: 3.19.5 dependencies: flutter: diff --git a/catalyst_voices/packages/catalyst_voices_blocs/pubspec.yaml b/catalyst_voices/packages/catalyst_voices_blocs/pubspec.yaml index 4a2086af4e0..40be3785b76 100644 --- a/catalyst_voices/packages/catalyst_voices_blocs/pubspec.yaml +++ b/catalyst_voices/packages/catalyst_voices_blocs/pubspec.yaml @@ -5,7 +5,7 @@ publish_to: none environment: sdk: ">=3.2.6 <4.0.0" - flutter: 3.19.0 + flutter: 3.19.5 dependencies: bloc: ^8.1.2 diff --git a/catalyst_voices/packages/catalyst_voices_localization/pubspec.yaml b/catalyst_voices/packages/catalyst_voices_localization/pubspec.yaml index f84bee54adc..ec80ae6fb2f 100644 --- a/catalyst_voices/packages/catalyst_voices_localization/pubspec.yaml +++ b/catalyst_voices/packages/catalyst_voices_localization/pubspec.yaml @@ -5,7 +5,7 @@ publish_to: none environment: sdk: ">=3.2.6 <4.0.0" - flutter: 3.19.0 + flutter: 3.19.5 dependencies: flutter: diff --git a/catalyst_voices/packages/catalyst_voices_repositories/pubspec.yaml b/catalyst_voices/packages/catalyst_voices_repositories/pubspec.yaml index 1e63f864694..a2453a86a7f 100644 --- a/catalyst_voices/packages/catalyst_voices_repositories/pubspec.yaml +++ b/catalyst_voices/packages/catalyst_voices_repositories/pubspec.yaml @@ -5,7 +5,7 @@ publish_to: none environment: sdk: ">=3.2.6 <4.0.0" - flutter: 3.19.0 + flutter: 3.19.5 dependencies: catalyst_voices_models: diff --git a/catalyst_voices/packages/catalyst_voices_services/pubspec.yaml b/catalyst_voices/packages/catalyst_voices_services/pubspec.yaml index 2c0fdb4df4f..652bfad765c 100644 --- a/catalyst_voices/packages/catalyst_voices_services/pubspec.yaml +++ b/catalyst_voices/packages/catalyst_voices_services/pubspec.yaml @@ -5,7 +5,7 @@ publish_to: none environment: sdk: ">=3.2.6 <4.0.0" - flutter: 3.19.0 + flutter: 3.19.5 dependencies: chopper: ^7.2.0 diff --git a/catalyst_voices/packages/catalyst_voices_shared/pubspec.yaml b/catalyst_voices/packages/catalyst_voices_shared/pubspec.yaml index 056d53e8fc5..83f33847d1e 100644 --- a/catalyst_voices/packages/catalyst_voices_shared/pubspec.yaml +++ b/catalyst_voices/packages/catalyst_voices_shared/pubspec.yaml @@ -4,8 +4,8 @@ version: 0.1.0+1 publish_to: none environment: - sdk: ">=3.3.0 <4.0.0" - flutter: 3.19.0 + sdk: ">=3.3.3 <4.0.0" + flutter: 3.19.5 dependencies: flutter: diff --git a/catalyst_voices/packages/catalyst_voices_view_models/pubspec.yaml b/catalyst_voices/packages/catalyst_voices_view_models/pubspec.yaml index 247d5605d0f..1edc768165a 100644 --- a/catalyst_voices/packages/catalyst_voices_view_models/pubspec.yaml +++ b/catalyst_voices/packages/catalyst_voices_view_models/pubspec.yaml @@ -5,7 +5,7 @@ publish_to: none environment: sdk: ">=3.2.6 <4.0.0" - flutter: 3.19.0 + flutter: 3.19.5 dependencies: equatable: ^2.0.5 diff --git a/catalyst_voices/pubspec.yaml b/catalyst_voices/pubspec.yaml index a0c5b33fbb4..92a3915f1d0 100644 --- a/catalyst_voices/pubspec.yaml +++ b/catalyst_voices/pubspec.yaml @@ -4,8 +4,8 @@ version: 0.1.0+1 publish_to: none environment: - sdk: ">=3.3.0 <4.0.0" - flutter: 3.19.0 + sdk: ">=3.3.3 <4.0.0" + flutter: 3.19.5 dependencies: animated_text_kit: ^4.2.2 diff --git a/melos.yaml b/melos.yaml index 10efc047f87..c2bd1cb76a0 100644 --- a/melos.yaml +++ b/melos.yaml @@ -13,8 +13,8 @@ command: workspaceChangelog: true bootstrap: environment: - sdk: ">=3.3.0 <4.0.0" - flutter: 3.19.0 + sdk: ">=3.3.3 <4.0.0" + flutter: 3.19.5 dependencies: bloc_concurrency: ^0.2.2 bloc: ^8.1.2 diff --git a/utilities/catalyst_voices_remote_widgets/pubspec.yaml b/utilities/catalyst_voices_remote_widgets/pubspec.yaml index 76fa84e835e..ecad9b816a0 100644 --- a/utilities/catalyst_voices_remote_widgets/pubspec.yaml +++ b/utilities/catalyst_voices_remote_widgets/pubspec.yaml @@ -4,7 +4,7 @@ version: 0.1.0+1 publish_to: none environment: - sdk: ">=3.3.0 <4.0.0" + sdk: ">=3.3.3 <4.0.0" flutter: 3.19.3 dependencies: From 26ad5028502cfabcfd02851a74c251718b7a8fb7 Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Wed, 10 Apr 2024 18:39:25 +0700 Subject: [PATCH 61/66] fix(frontend): more flutter/dart version corrections --- .../catalyst_analysis/example/pubspec.yaml | 4 ++-- catalyst_voices_packages/catalyst_analysis/pubspec.yaml | 2 +- pubspec.yaml | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/catalyst_voices_packages/catalyst_analysis/example/pubspec.yaml b/catalyst_voices_packages/catalyst_analysis/example/pubspec.yaml index ee9b9ad454c..f857ad549cb 100644 --- a/catalyst_voices_packages/catalyst_analysis/example/pubspec.yaml +++ b/catalyst_voices_packages/catalyst_analysis/example/pubspec.yaml @@ -4,8 +4,8 @@ description: A project that showcases how to enable the recommended lints for Ca publish_to: none environment: - sdk: '>=3.3.0 <4.0.0' + sdk: ">=3.3.3 <4.0.0" dev_dependencies: catalyst_analysis: - path: ../ \ No newline at end of file + path: ../ diff --git a/catalyst_voices_packages/catalyst_analysis/pubspec.yaml b/catalyst_voices_packages/catalyst_analysis/pubspec.yaml index 15b868bf660..31a35c67c37 100644 --- a/catalyst_voices_packages/catalyst_analysis/pubspec.yaml +++ b/catalyst_voices_packages/catalyst_analysis/pubspec.yaml @@ -6,4 +6,4 @@ issue_tracker: https://github.com/input-output-hk/catalyst-voices/issues topics: [lints, analyzer, analysis] environment: - sdk: '>=3.3.0 <4.0.0' + sdk: ">=3.3.3 <4.0.0" diff --git a/pubspec.yaml b/pubspec.yaml index a6af3c302dd..c5e67b52d98 100644 --- a/pubspec.yaml +++ b/pubspec.yaml @@ -1,7 +1,7 @@ name: catalyst_voices_workspace environment: - sdk: '>=3.3.0 <4.0.0' + sdk: ">=3.3.3 <4.0.0" dev_dependencies: melos: ^5.2.2 From b9ed28ecfbde824db360023eeb04fbaa24d834ce Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Wed, 10 Apr 2024 18:53:19 +0700 Subject: [PATCH 62/66] fix(frontend): Revert flutter files to same as main branch --- .../example/pubspec.yaml | 2 +- .../catalyst_voices_assets/pubspec.yaml | 2 +- .../catalyst_voices_blocs/pubspec.yaml | 42 +++++++++---------- .../catalyst_voices_services/pubspec.yaml | 2 +- .../catalyst_voices_shared/pubspec.yaml | 11 ++--- 5 files changed, 30 insertions(+), 29 deletions(-) diff --git a/catalyst_voices/packages/catalyst_voices_assets/example/pubspec.yaml b/catalyst_voices/packages/catalyst_voices_assets/example/pubspec.yaml index 07900cac01c..40336f3b7ab 100644 --- a/catalyst_voices/packages/catalyst_voices_assets/example/pubspec.yaml +++ b/catalyst_voices/packages/catalyst_voices_assets/example/pubspec.yaml @@ -14,4 +14,4 @@ dependencies: sdk: flutter flutter: - uses-material-design: true + uses-material-design: true \ No newline at end of file diff --git a/catalyst_voices/packages/catalyst_voices_assets/pubspec.yaml b/catalyst_voices/packages/catalyst_voices_assets/pubspec.yaml index b658ab5e903..1f15832aa5f 100644 --- a/catalyst_voices/packages/catalyst_voices_assets/pubspec.yaml +++ b/catalyst_voices/packages/catalyst_voices_assets/pubspec.yaml @@ -43,4 +43,4 @@ flutter_gen: outputs: class_name: VoicesColors inputs: - - assets/colors/colors.xml + - assets/colors/colors.xml \ No newline at end of file diff --git a/catalyst_voices/packages/catalyst_voices_blocs/pubspec.yaml b/catalyst_voices/packages/catalyst_voices_blocs/pubspec.yaml index 40be3785b76..1a2d0d64f27 100644 --- a/catalyst_voices/packages/catalyst_voices_blocs/pubspec.yaml +++ b/catalyst_voices/packages/catalyst_voices_blocs/pubspec.yaml @@ -8,27 +8,27 @@ environment: flutter: 3.19.5 dependencies: - bloc: ^8.1.2 - bloc_concurrency: ^0.2.2 - catalyst_voices_models: - path: ../catalyst_voices_models - catalyst_voices_repositories: - path: ../catalyst_voices_repositories - catalyst_voices_services: - path: ../catalyst_voices_services - catalyst_voices_view_models: - path: ../catalyst_voices_view_models - collection: ^1.17.1 - equatable: ^2.0.5 - flutter: - sdk: flutter - formz: ^0.7.0 - get_it: ^7.6.7 - meta: ^1.10.0 - result_type: ^0.2.0 + bloc: ^8.1.2 + bloc_concurrency: ^0.2.2 + catalyst_voices_models: + path: ../catalyst_voices_models + catalyst_voices_repositories: + path: ../catalyst_voices_repositories + catalyst_voices_services: + path: ../catalyst_voices_services + catalyst_voices_view_models: + path: ../catalyst_voices_view_models + collection: ^1.17.1 + equatable: ^2.0.5 + flutter: + sdk: flutter + formz: ^0.7.0 + get_it: ^7.6.7 + meta: ^1.10.0 + result_type: ^0.2.0 dev_dependencies: - bloc_test: ^9.1.4 - catalyst_analysis: + bloc_test: ^9.1.4 + catalyst_analysis: path: ../../../catalyst_voices_packages/catalyst_analysis - test: ^1.24.9 + test: ^1.24.9 diff --git a/catalyst_voices/packages/catalyst_voices_services/pubspec.yaml b/catalyst_voices/packages/catalyst_voices_services/pubspec.yaml index 652bfad765c..3594867114b 100644 --- a/catalyst_voices/packages/catalyst_voices_services/pubspec.yaml +++ b/catalyst_voices/packages/catalyst_voices_services/pubspec.yaml @@ -22,4 +22,4 @@ dev_dependencies: chopper_generator: ^7.2.0 json_serializable: ^6.7.1 swagger_dart_code_generator: ^2.15.2 - test: ^1.24.9 + test: ^1.24.9 \ No newline at end of file diff --git a/catalyst_voices/packages/catalyst_voices_shared/pubspec.yaml b/catalyst_voices/packages/catalyst_voices_shared/pubspec.yaml index 83f33847d1e..e9e7014efbf 100644 --- a/catalyst_voices/packages/catalyst_voices_shared/pubspec.yaml +++ b/catalyst_voices/packages/catalyst_voices_shared/pubspec.yaml @@ -4,7 +4,7 @@ version: 0.1.0+1 publish_to: none environment: - sdk: ">=3.3.3 <4.0.0" + sdk: '>=3.3.3 <4.0.0' flutter: 3.19.5 dependencies: @@ -13,8 +13,9 @@ dependencies: web: ^0.5.0 dev_dependencies: - catalyst_analysis: + catalyst_analysis: path: ../../../catalyst_voices_packages/catalyst_analysis - flutter_test: - sdk: flutter - test: ^1.24.9 + flutter_test: + sdk: flutter + test: ^1.24.9 + From 1dc7ddfdd927ce359677bdff25cefe387a730b65 Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Wed, 10 Apr 2024 19:13:11 +0700 Subject: [PATCH 63/66] fix(frontend): revert more flutter .yml files to those in main --- .../packages/catalyst_voices_view_models/pubspec.yaml | 4 ++-- catalyst_voices/pubspec.yaml | 8 ++++---- .../catalyst_analysis/example/pubspec.yaml | 4 ++-- catalyst_voices_packages/catalyst_analysis/pubspec.yaml | 2 +- melos.yaml | 8 ++++---- pubspec.yaml | 2 +- utilities/catalyst_voices_remote_widgets/pubspec.yaml | 2 +- 7 files changed, 15 insertions(+), 15 deletions(-) diff --git a/catalyst_voices/packages/catalyst_voices_view_models/pubspec.yaml b/catalyst_voices/packages/catalyst_voices_view_models/pubspec.yaml index 1edc768165a..c5cbffb382b 100644 --- a/catalyst_voices/packages/catalyst_voices_view_models/pubspec.yaml +++ b/catalyst_voices/packages/catalyst_voices_view_models/pubspec.yaml @@ -14,6 +14,6 @@ dependencies: formz: ^0.7.0 dev_dependencies: - catalyst_analysis: + catalyst_analysis: path: ../../../catalyst_voices_packages/catalyst_analysis - test: ^1.24.9 + test: ^1.24.9 \ No newline at end of file diff --git a/catalyst_voices/pubspec.yaml b/catalyst_voices/pubspec.yaml index 92a3915f1d0..8eb65dd770d 100644 --- a/catalyst_voices/pubspec.yaml +++ b/catalyst_voices/pubspec.yaml @@ -4,7 +4,7 @@ version: 0.1.0+1 publish_to: none environment: - sdk: ">=3.3.3 <4.0.0" + sdk: '>=3.3.3 <4.0.0' flutter: 3.19.5 dependencies: @@ -44,9 +44,9 @@ dev_dependencies: build_verify: ^3.1.0 catalyst_analysis: git: - url: https://github.com/input-output-hk/catalyst-voices.git - path: catalyst_voices_packages/catalyst_analysis - ref: 3431f7b + url: https://github.com/input-output-hk/catalyst-voices.git + path: catalyst_voices_packages/catalyst_analysis + ref: 3431f7b flutter_test: sdk: flutter go_router_builder: ^2.4.1 diff --git a/catalyst_voices_packages/catalyst_analysis/example/pubspec.yaml b/catalyst_voices_packages/catalyst_analysis/example/pubspec.yaml index f857ad549cb..3b5ad986b44 100644 --- a/catalyst_voices_packages/catalyst_analysis/example/pubspec.yaml +++ b/catalyst_voices_packages/catalyst_analysis/example/pubspec.yaml @@ -4,8 +4,8 @@ description: A project that showcases how to enable the recommended lints for Ca publish_to: none environment: - sdk: ">=3.3.3 <4.0.0" + sdk: '>=3.3.3 <4.0.0' dev_dependencies: catalyst_analysis: - path: ../ + path: ../ \ No newline at end of file diff --git a/catalyst_voices_packages/catalyst_analysis/pubspec.yaml b/catalyst_voices_packages/catalyst_analysis/pubspec.yaml index 31a35c67c37..302fabebba1 100644 --- a/catalyst_voices_packages/catalyst_analysis/pubspec.yaml +++ b/catalyst_voices_packages/catalyst_analysis/pubspec.yaml @@ -6,4 +6,4 @@ issue_tracker: https://github.com/input-output-hk/catalyst-voices/issues topics: [lints, analyzer, analysis] environment: - sdk: ">=3.3.3 <4.0.0" + sdk: '>=3.3.3 <4.0.0' diff --git a/melos.yaml b/melos.yaml index c2bd1cb76a0..ca213ddd4f9 100644 --- a/melos.yaml +++ b/melos.yaml @@ -13,7 +13,7 @@ command: workspaceChangelog: true bootstrap: environment: - sdk: ">=3.3.3 <4.0.0" + sdk: '>=3.3.0 <4.0.0' flutter: 3.19.5 dependencies: bloc_concurrency: ^0.2.2 @@ -34,8 +34,8 @@ scripts: description: Run all static analysis checks. format: - run: melos exec dart format . --fix - description: Run `dart format` for all packages. + run: melos exec dart format . --fix + description: Run `dart format` for all packages. format-check: run: melos exec dart format . --set-exit-if-changed @@ -77,4 +77,4 @@ scripts: run: flutter pub get exec: concurrency: 6 - description: Install all dependencies + description: Install all dependencies \ No newline at end of file diff --git a/pubspec.yaml b/pubspec.yaml index c5e67b52d98..1decd7e9e98 100644 --- a/pubspec.yaml +++ b/pubspec.yaml @@ -1,7 +1,7 @@ name: catalyst_voices_workspace environment: - sdk: ">=3.3.3 <4.0.0" + sdk: '>=3.3.3 <4.0.0' dev_dependencies: melos: ^5.2.2 diff --git a/utilities/catalyst_voices_remote_widgets/pubspec.yaml b/utilities/catalyst_voices_remote_widgets/pubspec.yaml index ecad9b816a0..76fa84e835e 100644 --- a/utilities/catalyst_voices_remote_widgets/pubspec.yaml +++ b/utilities/catalyst_voices_remote_widgets/pubspec.yaml @@ -4,7 +4,7 @@ version: 0.1.0+1 publish_to: none environment: - sdk: ">=3.3.3 <4.0.0" + sdk: ">=3.3.0 <4.0.0" flutter: 3.19.3 dependencies: From fc7f4622a5dd640175888e951de01050d51fb0e9 Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Wed, 10 Apr 2024 23:07:50 +0700 Subject: [PATCH 64/66] fix(cips): Fix links between files --- .../draft-cips/x509-envelope-metadata/cip-509A.md | 2 +- .../draft-cips/x509-role-registration-metadata/cip-509B.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/cip-509A.md b/docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/cip-509A.md index 143bd2d645c..4094c25ec8b 100644 --- a/docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/cip-509A.md +++ b/docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/cip-509A.md @@ -219,7 +219,7 @@ Code samples and reference material are licensed under [Apache 2.0] [CC-BY-4.0]: https://creativecommons.org/licenses/by/4.0/legalcode [Apache 2.0]: https://www.apache.org/licenses/LICENSE-2.0.html -[x509 Metadata Envelope CDDL]: ./x509_envelope.cddl +[x509 Metadata Envelope CDDL]: ./x509-envelope.cddl [specification for the encoding of all Cardano metadata]: https://github.com/IntersectMBO/cardano-ledger/blob/ab8d57cf43be912a336e872b68d1a2526c93dc6a/eras/conway/impl/cddl-files/conway.cddl#L511-L531 [dCBOR]: https://datatracker.ietf.org/doc/draft-mcnally-deterministic-cbor/ [Brotli]: https://github.com/google/brotli diff --git a/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/cip-509B.md b/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/cip-509B.md index a0ff97b6513..6d02b8142d7 100644 --- a/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/cip-509B.md +++ b/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/cip-509B.md @@ -78,7 +78,7 @@ and only on-chain interaction requires interaction with a Wallet. ## Specification -Role registration is encapsulated inside a [x509 Envelope](../x509-envelope-metadata/cip-xxxx.md) metadata record. +Role registration is encapsulated inside a [x509 Envelope](../x509-envelope-metadata/cip-509A.md) metadata record. This enables the data to both be compressed, saving on-chain space and also to have more expressivity and less restrictions vs raw on-chain metadata. @@ -167,7 +167,7 @@ At a high level, Role registration will collect the following data: 3. An [optional list](#simple-public-keys) list of tagged simple public keys. 4. An [optional certificate revocation](#certificate-revocation-list) set. 5. An [optional set](#role-definitions) of role registration data. -6. An [optional list] of purpose specific data. +6. An [optional list](#dapp-specific-registration-data) of purpose specific data. ### x509 Certificate Lists From d4a2b689626bb12e6c1627cc95c45dfc98d80b89 Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Thu, 11 Apr 2024 00:29:56 +0700 Subject: [PATCH 65/66] docs(cips): Add catalyst specific role registration documentation --- .../cip-catalyst-roles.md | 351 +++++++++++ .../cip-xxxx.md | 69 --- .../images/certificate-chain.d2 | 10 +- .../images/certificate-chain.svg | 574 +++++++++--------- 4 files changed, 643 insertions(+), 361 deletions(-) create mode 100644 docs/src/catalyst-standards/draft-cips/project-catalyst-x509-role-defintions/cip-catalyst-roles.md delete mode 100644 docs/src/catalyst-standards/draft-cips/project-catalyst-x509-role-defintions/cip-xxxx.md rename docs/src/catalyst-standards/draft-cips/{ => project-catalyst-x509-role-defintions}/images/certificate-chain.d2 (97%) rename docs/src/catalyst-standards/draft-cips/{ => project-catalyst-x509-role-defintions}/images/certificate-chain.svg (82%) diff --git a/docs/src/catalyst-standards/draft-cips/project-catalyst-x509-role-defintions/cip-catalyst-roles.md b/docs/src/catalyst-standards/draft-cips/project-catalyst-x509-role-defintions/cip-catalyst-roles.md new file mode 100644 index 00000000000..fb38bb3df52 --- /dev/null +++ b/docs/src/catalyst-standards/draft-cips/project-catalyst-x509-role-defintions/cip-catalyst-roles.md @@ -0,0 +1,351 @@ +--- +CIP: /? +Title: Project Catalyst Role Registrations +Category: MetaData +Status: Proposed +Authors: + - Steven Johnson +Implementors: [] +Discussions: + - https://github.com/cardano-foundation/cips/pulls/? +Created: 2023-10-24 +License: CC-BY-4.0 +--- + +## Abstract + +Project Catalyst requires better role registration and is utilizing x509 certificate RBAC for this purpose. +This document defines how that standard is applied to Project Catalyst role registrations. + +## Motivation: why is this CIP necessary? + +As the project catalyst dApp grew, +it became clear there was a need for an extensible and flexible Role based Access control system to support its needs. + +This CIP builds upon the x509 RBAC Specification CIPs and defines how they are used for Project Catalyst Roles. + +## Specification + +Project Catalyst defines 2 dApp ID's. + +| dApp ID | Role Group | +| --- | --- | +| `ca7a1457-ef9f-4c7f-9c74-7f8c4a4cfa6c` | Project Catalyst User Role Registrations | +| `ca7ad312-a19b-4412-ad53-2a36fb14e2e5` | Project Catalyst Admin Role Registrations | + +User Roles are self registered by individual users. +Admin roles are managed. + +We define these two RBAC Role Groups to allow them to be managed in an easier way. + +### Project Catalyst User Role Registrations + +The following user roles are defined: + +| Role ID | Role Description | +| -- | -- | +| 0 | Voter | +| 1 | Delegated Representative | +| 2 | Voter Delegation | +| 3 | Proposer | + +Further User roles will be added to this specification as those roles are defined. + +#### Voter Role + +Voters are the most basic role within Project Catalyst. +They can Vote and Comment on Proposals. +They MAY earn rewards for their participation, and MAY earn reputation. + +X509 registrations require a Role 0 registration. +Role 0 is the Basic Voter Role. + +The Role 0 registration certificate MUST be linked to AT LEAST ONE stake address on-chain. +It can be linked to multiple stake addresses, but they must all be witnessed in the transaction to be valid. + +The Voters Role 0 signing key from their certificate is also used by the voter to: + +1. Establish their identity to backend systems (Decentralized Authorization). +2. Sign votes in a Catalyst event. +3. Witness Comments made on proposals. + +The Certificate MUST be self signed. +Currently CA's are not supported for Catalyst User Roles. + +The Project Catalyst dApp generates a Public/Private key pair and creates the user Role 0 certificate, +associates it with their on-chain stake address, and signs the certificate. + +This allows each user to have full custody of their own Catalyst voting identity. +They may also change their Signing Key at any time by rolling their Role 0 certificate as described +in the x509 metadata specifications. + +In the initial implementation the Signing key used in the certificate MUST BE an ED25519 certificate. +No other kind of signature algorithm is allowed. + +#### Delegated Representative (dRep) + +A dRep is a registration that is made, which allows for voters to give their voting power to the dRep who +then votes on their behalf. + +dReps must register a simple signing key, it must be referenced to the first signing key in the simple key array. +dReps do not use certificates to manage their signing key. + +dReps may register a new Payment address, if they do not register a new payment address, the payment address +registered to Role 0 will be used for the dRep rewards. + +dReps MAY attach extra information to their registration: + +| Data Key | Information | +| -- | -- | +| 10 | Name | +| 11 | [ + URL Link to Profile ] | +| 12 | ADA Handle | + +#### Voter Delegation + +A Voter Delegation role assigns a voters voting power to a registered dRep. + +The dRep, will use the voters voting power, pooled with other delegations to vote on behalf of the voter. + +Delegation does not define a signing key, not an encryption key. + +Delegation roles ONLY contain a dApp specific data as defined here: + +| Data Key | Information | +| -- | -- | +| 10 | `[ + Delegation Record] / undefined` | +| 11 | Optional Time to live | +| 12 | Optional fund id | +| 13 | Optional purpose | + +##### Delegation Record + +Key 10 defines an array of Delegation records. + +The formal structure of the Delegation Record is defined as: + +```cddl +delegation_registration = [ + delegation_record ] / undefined + +delegation_record = ( + simple_delegation / + weighted_delegation +) + +simple_delegation = drep_key_hash +weighted_delegation = [ drep_key_hash, weight ] + +drep_key_hash = bytes .size 16 +weight = uint +``` + +* `delegation_registration` is either an array of delegation_records OR `undefined`. + `undefined` means that any previous delegation that was active is terminated. + The voter retains their voting power in this case. +* An individual `delegation_record` can be either a `simple_delegation` or a `weighted_delegation`. +* `simple_delegation` is just the hash of the drep voting key to be delegated to. + A weight of `1` is assumed if there are multiple delegations. +* `weighted_delegation` allows the weight to be defined, it is a positive integer. + Weight apportions a voters voting power between all dReps delegated to. + +Voting Power weighted apportionment is a function of the wights. +The total of the weights is added to give `total_weight`. +Each dRep get `voting power * (weight / total_weight)` worth of voting power from the delegation. +In the event there is any residual voting power, it is assigned to the final dRep in the list. + +##### Optional Time To Live + +This is a unit, and is the time expressed as seconds since 1970 UTC. +When this time is reached, the delegation is automatically cancelled, if it was not previously de-registered. + +Time To Live can be used to remove a delegation at any time. +However, if the Delegation has been used to vote before the Time to Live expired, the voter may not ALSO Vote. + +This allows the TTL to act as a safety. +For example, if the TTL is set to 10 days into a 15 day voting period, +then the dRep MUST vote within the first 10 days, after which they lose the delegation. +Having lost the delegation, the Voter may vote at any time in the final 5 days. +If however, the dRep voted in the first 10 days, the Voter may not vote in the last 5. +Even though they delegation expired. +That is because it is only valid to vote once on a proposal during a fund and the voter +already voted (via the valid, at the time, delegation). + +##### Optional Fund ID + +This is simply the ID of the fund. +It is a `uint`. +This defines the Fund for which the delegation is active. + +##### Optional Delegation Purpose + +This field can ONLY be defined if the `Fund ID` field is defined. + +The Purpose defines what the delegation is for. +For example, in Catalyst it is defined as the number of the challenge or category in the fund the delegation is used for. +The delegation in this case is only valid for this Purpose on the specified Fund. + +##### Multiple Delegations + +It is possible for a Voter to have multiple simultaneous delegations. +In this case, the most specific delegation that has not expired is the one that is used. + +For example, IF there is a delegation for Fund 15, Challenge 3, and no other delegations. +Then the voter can vote on every other challenge, except for Challenge 3 in that Fund. +Challenge 3 can be voted on by the dReps that were delegated. + +In another example, if a voter has a general delegation, but also a specific delegation for Fund 15, Challenge 3. +Then the general delegations can vote on behalf of the voter for any fund/challenge +EXCEPT for Fund 15, Challenge 3. +For Fund 15, Challenge 3 ONLY the specific delegations for the Challenge/Fund may vote for the voter. + +##### Validity + +The Fund may impose rules on the construction of a delegation. +The delegation will not be valid if it does not conform to those rules. +For example, the Fund can define that ALL delegations Must expire 10 days within a 15 day voting window. +In which case, for a delegation to be valid, the TTL MUST be set appropriately. + +This allows for great flexibility in how delegations work, but also allows fund specific rules to be created. +Without limiting the general usefulness of the registration format itself. + +#### Proposer Registration + +Registering as a proposer allows the registered entity to: + +1. Create and Edit their own proposals both anonymously and publicly. +2. Jointly Edit proposals with other registered proposers. +3. Respond to comments on public proposals. +4. Sign a proposal either singly or jointly for submission and consideration in a Catalyst Fund. +5. Be paid to a certified payment address if the proposal wins. + +Proposers MUST define a Proposers signature public key. +It must be a simple public key of the type ED25519, and it must reference the second signing key in the simple key array. + +The proposer registration may OPTIONALLY define an encryption key. +Currently only X25519 encryption is supported, and this must be a reference to the second or third key in the simple key array. +IF the key is an ED25519 key, the X25519 public key is derived from it. +Otherwise if the key is an X25519 key, it is used as specified. + +This allows the Propers signing key to also be used as a public encryption key. + +A Proposer may ONLY work on private encrypted proposals if they have a published public encryption key. +The proposer may change their public encryption key at any time by posting an update to their registration. + +Proposers MAY attach extra information to their registration: + +| Data Key | Information | +| -- | -- | +| 10 | Name | +| 11 | [ + URL Link to Profile ] | +| 12 | ADA Handle | + +If the proposers registration does not define a payment key, +the Role 0 payment key is used for the proposers payment key. + +Because the purpose of a Proposer is to earn funding from the Catalyst Fund, +A proposal registration is INVALID if it does not have an associated payment address. + +#### dApp purpsoe specific keys + +Project Catalyst defines the following data which can be declared globally in any registration. + +| Data Key | Information | +| -- | -- | +| 200 | Name | +| 201 | [ + URL Link to Profile ] | +| 202 | ADA Handle | + +If any of these data items is defined in a registration, +they will be used if the matching key is absent in either a dRep or Proposer registration. + +This allows for an individual that is both a dRep and a Proposer to share the same extended data about their registration. + +### Project Catalyst Admin Role Registrations + +| Role ID | Role Description | +| -- | -- | +| 0 | General Admin Role | + +#### General Admin Role + +Project Catalyst will register on-chain a registration for it's CA. +The CA will be associated with a known stake address. +The assignment of the CA to the known catalyst stake address establishes trust in the +Admin CA and ensures that other fraudulent CA's can not be registered. + +The Admin CA can then issue other certificates for admins. +It may also revoke them. +It can also create a 2nd layer of CA's to create Admin users. + +An example of the relationship between CA's and certificates is: + +![Certificate Chain](./images/certificate-chain.svg) + +The CA defined in this way, or the intermediate CA does not have any Admin privileges. + +Only End Entity Certificates have Admin privileges. +Initially all registered project catalyst admins have all admin privileges in the system. + +However, if required, an extension within the Role 0 certificate. +That is issued to theAdmin by the CA or intermediate CA. +Can define restrictions to the Admin role. +It is the responsibility of the CA to ensure the +permissions encoded in the admins Role 0 certificate are correct. + +The CA or Intermediate CA may revoke an admins certificate at any time. +They do so by publishing the Admins certificate hash in a revocation list signed by the CA. + +If an Admin user has their certificate revoked, they lose all Admin functionality. + +This system allows a trusted and verifiable CA to register administrators and prevents fraudulent admins being registered. + +Each Admin and CA must have a Stake Address associated with their registration certificate. + +Admins are Role 0, so their signing key is defined by their certificate. +They may also register an Encryption key by referencing a key at index 0 of the simple key list. + +The encryption key must be an X25519 public key if registered. + +Admin users must NOT register a payment key, and they have no other data associated with their role registration. + +### Special Roles not defined by x509 certificates + +There is one special role within project catalyst which is not defined by the +Role registration. + +An Unregistered Voter. + +#### Unregistered Voter + +Project Catalyst will have the concept of an UNREGISTERED voter. +A Voter may sign a vote with either their registered Voting Key, OR +They may sign it with their stake address. + +As long as the stake address is valid, then anyone with a wallet can vote. +Even if they have not registered as a catalyst voter. + +Alternatively a Voter who has a faulty registration or has lost their private voting +key may still vote in a fund with their Stake address signing their vote. +This acts as a fail safe in these cases. + +Regardless of which key is used to sign the vote, a voter may ONLY vote once per fund per proposal. +All possible voting signature keys are considered equivalent. + +Stake addresses may only be used for voting and can not be used for other functions assigned to Role 0. + +## Rationale: how does this CIP achieve its goals? + +## Path to Active + +### Acceptance Criteria + +### Implementation Plan + +## Copyright + +This CIP is licensed under [CC-BY-4.0] + +Code samples and reference material are licensed under [Apache 2.0] + +[CC-BY-4.0]: https://creativecommons.org/licenses/by/4.0/legalcode +[Apache 2.0]: https://www.apache.org/licenses/LICENSE-2.0.html diff --git a/docs/src/catalyst-standards/draft-cips/project-catalyst-x509-role-defintions/cip-xxxx.md b/docs/src/catalyst-standards/draft-cips/project-catalyst-x509-role-defintions/cip-xxxx.md deleted file mode 100644 index 569f48955e3..00000000000 --- a/docs/src/catalyst-standards/draft-cips/project-catalyst-x509-role-defintions/cip-xxxx.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -CIP: /? -Title: Role based Access Control Registration -Category: MetaData -Status: Proposed -Authors: - - Steven Johnson -Implementors: [] -Discussions: - - https://github.com/cardano-foundation/cips/pulls/? -Created: 2023-10-24 -License: CC-BY-4.0 ---- - - - - -# Role Based Access Control Registration - -## Abstract - - -## Motivation: why is this CIP necessary? - - -## Specification - - -## Rationale: how does this CIP achieve its goals? - - -## Path to Active - -### Acceptance Criteria - - -### Implementation Plan - - -## Copyright - diff --git a/docs/src/catalyst-standards/draft-cips/images/certificate-chain.d2 b/docs/src/catalyst-standards/draft-cips/project-catalyst-x509-role-defintions/images/certificate-chain.d2 similarity index 97% rename from docs/src/catalyst-standards/draft-cips/images/certificate-chain.d2 rename to docs/src/catalyst-standards/draft-cips/project-catalyst-x509-role-defintions/images/certificate-chain.d2 index df7b931d270..409d7be0abd 100644 --- a/docs/src/catalyst-standards/draft-cips/images/certificate-chain.d2 +++ b/docs/src/catalyst-standards/draft-cips/project-catalyst-x509-role-defintions/images/certificate-chain.d2 @@ -28,13 +28,13 @@ classes: { } title: |md - # Chaining Certificates + # Chaining Certificates. | { - # shape: text + shape: text near: top-center - # style: { - # font-size: 8 - # } + style: { + font-size: 25 + } } root-ca: "ROOT CERTIFICATE AUTHORITY (CA)" { diff --git a/docs/src/catalyst-standards/draft-cips/images/certificate-chain.svg b/docs/src/catalyst-standards/draft-cips/project-catalyst-x509-role-defintions/images/certificate-chain.svg similarity index 82% rename from docs/src/catalyst-standards/draft-cips/images/certificate-chain.svg rename to docs/src/catalyst-standards/draft-cips/project-catalyst-x509-role-defintions/images/certificate-chain.svg index fc5e0caef52..7563ab84e3c 100644 --- a/docs/src/catalyst-standards/draft-cips/images/certificate-chain.svg +++ b/docs/src/catalyst-standards/draft-cips/project-catalyst-x509-role-defintions/images/certificate-chain.svg @@ -1,13 +1,13 @@ -

Chaining Certificates

-
ROOT CERTIFICATE AUTHORITY (CA)INTERMEDIATE CERTIFICATE AUTHORITY (CA)End-Entity Certificatepad Root CA's Key PairprivateSecretpublicSharedRoot Certificate (ROOT CA)Subject`s NameROOT CA NameSubject`s PublicKeyPublic KeyIssuer`s NameROOT CA NameIssuer`s SignatureSignatureSubject Alt. NameURI:S:ada:stake1vpu...p0u Intermediate CA's Key PairprivateSecretpublicSharedIntermediate Certificate (Intermediate CA)Subject`s NameIntermediate CA NameSubject`s PublicKeyPublic KeyIssuer`s NameRoot CA NameIssuer`s SignatureSignatureSubject Alt. NameURI:S:ada:stake1ngf...8dyURI:S:ada:cc_cold16cj..80v Entities Key PairprivateSecretpublicSharedIntermediate Certificate (Intermediate CA)Subject`s NameEntities NameSubject`s PublicKeyPublic KeyIssuer`s NameIntermediate CA NameIssuer`s SignatureSignatureSubject Alt. NameURI:S:ada:stake1ngf...v2qURI:S:ada:drep1ayt..80v Published Self SignPublishedSign ReferencesVerifiesPublishedVerifiesSignReferences - - +

Chaining Certificates.

+
ROOT CERTIFICATE AUTHORITY (CA)INTERMEDIATE CERTIFICATE AUTHORITY (CA)End-Entity Certificatepad Root CA's Key PairprivateSecretpublicSharedRoot Certificate (ROOT CA)Subject`s NameROOT CA NameSubject`s PublicKeyPublic KeyIssuer`s NameROOT CA NameIssuer`s SignatureSignatureSubject Alt. NameURI:S:ada:stake1vpu...p0u Intermediate CA's Key PairprivateSecretpublicSharedIntermediate Certificate (Intermediate CA)Subject`s NameIntermediate CA NameSubject`s PublicKeyPublic KeyIssuer`s NameRoot CA NameIssuer`s SignatureSignatureSubject Alt. NameURI:S:ada:stake1ngf...8dyURI:S:ada:cc_cold16cj..80v Entities Key PairprivateSecretpublicSharedIntermediate Certificate (Intermediate CA)Subject`s NameEntities NameSubject`s PublicKeyPublic KeyIssuer`s NameIntermediate CA NameIssuer`s SignatureSignatureSubject Alt. NameURI:S:ada:stake1ngf...v2qURI:S:ada:drep1ayt..80v Published Self SignPublishedSign ReferencesVerifiesPublishedVerifiesSignReferences + + From cb687d0a938ba944895208aeb14d8b18d180d8c0 Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Thu, 11 Apr 2024 00:36:38 +0700 Subject: [PATCH 66/66] docs(spelling): fix spelling --- .../project-catalyst-x509-role-defintions/cip-catalyst-roles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/catalyst-standards/draft-cips/project-catalyst-x509-role-defintions/cip-catalyst-roles.md b/docs/src/catalyst-standards/draft-cips/project-catalyst-x509-role-defintions/cip-catalyst-roles.md index fb38bb3df52..e953692dbc4 100644 --- a/docs/src/catalyst-standards/draft-cips/project-catalyst-x509-role-defintions/cip-catalyst-roles.md +++ b/docs/src/catalyst-standards/draft-cips/project-catalyst-x509-role-defintions/cip-catalyst-roles.md @@ -245,7 +245,7 @@ the Role 0 payment key is used for the proposers payment key. Because the purpose of a Proposer is to earn funding from the Catalyst Fund, A proposal registration is INVALID if it does not have an associated payment address. -#### dApp purpsoe specific keys +#### dApp purpose specific keys Project Catalyst defines the following data which can be declared globally in any registration.