Merge branch 'main' into chore/update-ci-versions

Author: kukkok3

.config/dictionaries/project.dic

@@ -49,6 +49,7 @@ coverallsapp
 cpus
 crontabs
 crontagged
+csprng
 cstring
 dalek
 dashmap
@@ -122,6 +123,7 @@ jorm
 jormungandr
 Jörmungandr
 jsonschema
+kiduri
 lcov
 Leay
 Leshiy
@@ -141,6 +143,7 @@ maindbname
 mapref
 mdlint
 mdns
+MEMMAP
 memx
 Metadatum
 mgrybyk
@@ -209,6 +212,8 @@ reqwest
 retriggering
 ristretto
 rlib
+rngs
+rsplit
 rulelist
 RULENAME
 runable
@@ -235,6 +240,7 @@ smac
 stevenj
 stringzilla
 subsec
+subnetwork
 symlinkat
 syscall
 tacho
@@ -262,8 +268,11 @@ unlinkat
 upnp
 ureq
 userid
+userinfo
 utimensat
 UTXO
+uuidv4
+uuidv7
 vitss
 Vkey
 vkeywitness

docs/src/architecture/08_concepts/rbac_kid_uri/.pages

@@ -0,0 +1,3 @@
+title: RBAC KID (Key Identifier) URI
+arrange:
+  - kiduri.md

docs/src/architecture/08_concepts/rbac_kid_uri/kiduri.md

@@ -0,0 +1,180 @@
+---
+Title: RBAC Key Identifier URI Specification
+Category: Catalyst
+Status: Proposed
+Authors:
+    - Steven Johnson <[email protected]>
+Implementors:
+    - Catalyst Fund 14
+Discussions: []
+Created: 2025-01-05
+License: CC-BY-4.0
+---
+
+* [Abstract](#abstract)
+* [Motivation: why is this CIP necessary?](#motivation-why-is-this-cip-necessary)
+* [Specification](#specification)
+  * [URI](#uri)
+  * [`scheme`](#scheme)
+  * [`authority`](#authority)
+    * [`authority` - `host`](#authority---host)
+      * [List of defined hosts](#list-of-defined-hosts)
+    * [`authority` - `userinfo`](#authority---userinfo)
+      * [Lists of defined subnetwork `userinfo` values](#lists-of-defined-subnetwork-userinfo-values)
+        * [Cardano](#cardano)
+  * [`path`](#path)
+* [Reference Implementation](#reference-implementation)
+* [Test Vectors](#test-vectors)
+* [Rationale: how does this CIP achieve its goals?](#rationale-how-does-this-cip-achieve-its-goals)
+* [Path to Active](#path-to-active)
+  * [Acceptance Criteria](#acceptance-criteria)
+  * [Implementation Plan](#implementation-plan)
+* [Copyright](#copyright)
+
+## Abstract
+
+Definition of a [URI] which allows for RBAC keys used for different purposes to be easily and
+unambiguously identified.
+
+## Motivation: why is this CIP necessary?
+
+There is a need to identify which Key from a RBAC registration was used to sign data.
+RBAC defines a universal keychain of different keys that can be used for different purposes.
+They can be used not only for Signatures, but also Encryption.
+
+Therefore, there needs to be an unambiguous and easy to lookup identifier to signify which key was
+used for a particular purpose.
+
+This document defines a [URI] scheme to unambiguously define a particular key with reference to a
+particular RBAC keychain.
+
+## Specification
+
+### URI
+
+The RBAC Kid is formatted using a [Universal Resource Identifier].
+Refer to [RFC3986] for the specification of the URI format.
+
+### `scheme`
+
+The [scheme](https://datatracker.ietf.org/doc/html/rfc3986#section-3.1) **MUST** be `kid.catalyst-rbac`;
+
+### `authority`
+
+The [authority](https://datatracker.ietf.org/doc/html/rfc3986#section-3.2) references the blockchain or network
+the key was registered within.
+
+It is perfectly valid for a Kid to reference a different network than the place where the Key is used.
+For example, a `cardano` KID can be used to post documents to `IPFS`.
+Its purpose is to define WHERE the key was registered, and nothing more.
+
+The Authority will consist of a `host` and optional `userinfo`.
+
+#### `authority` - `host`
+
+The [host](https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2)
+refers to the network type where the RBAC registration was made.
+It **IS NOT** resolvable with **DNS**, and **IS NOT** a public host name.
+It is used as a decentralized network identifier.
+The consumer of the `KID` must be able to resolve these host names.
+
+##### List of defined hosts
+
+| `host` | Description |
+| --- | --- |
+| `cardano` | Cardano Blockchain |
+| `midnight` | Midnight Blockchain |
+| `ethereum` | Ethereum Blockchain |
+| `cosmos` | Cosmos Blockchain |
+
+#### `authority` - `userinfo`
+
+The [userinfo](https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1)
+is used to distinguish a subnetwork from the primary main network.
+The absence of `userinfo` is used to indicate the primary main network.
+
+##### Lists of defined subnetwork `userinfo` values
+
+###### Cardano
+
+| `userinfo` | Description |
+| --- | --- |
+| `preprod` | Cardano Pre-Production Network |
+| `preview` | Cardano Preview Network |
+| 0x<hex_number>  | Cardano network identified by this magic number in hex |
+
+### `path`
+
+The [path](https://datatracker.ietf.org/doc/html/rfc3986#section-3.3) defines the actual key within the registration.
+Keys are defined relative to the very first Role0 Key registered in any RBAC registration.
+
+The overall `path` specification is: `<initial role0 key>/<role>/<rotation>#encrypt`
+
+* `<initial role 0 key>` - This is the very first role 0 key used to post the registration to the network.
+  * It is the [Base64 URL] encoded binary data of the role 0 public key.
+  * This does not change, even if the Initial Role 0 key is revoked.
+  * This allows for an unambiguous identifier for the RBAC keychain.
+  * It is not necessarily the key being identified.
+* `<role>` - This is the Role number being used.
+  * It is a positive number, starting at 0, and no greater than 65535.
+* `<rotation>` - This is the rotation of the defined role key being identified.
+  * It starts at 0 for the first published key for the role, and increments by one for each subsequent published rotation.
+  * This number refers to the published sequence of keys for the role in the RBAC registration keychain,
+  not the index used in the key derivation.
+  * It is positive and no greater than 65535.
+* `#encrypt` - [Fragment](https://datatracker.ietf.org/doc/html/rfc3986#section-3.5)
+  disambiguates Encryption Public Keys from signing public keys.
+  * Roles can have 1 active public signing key, and 1 active public encryption key.
+  * By default, the URL is referencing the signing public key.
+  * If a public encryption key is being identified, then the fragment `#encrypt` is appended to the [Universal Resource Identifier].
+
+## Reference Implementation
+
+The first implementation will be Catalyst Voices.
+
+## Test Vectors
+
+* `kid.catalyst-rbac://cardano/<key>/0/0`
+  * A Signing key registered on the Cardano Main network.
+  * Role 0 - Rotation 0.
+  In this example, it is exactly the same as the `<key>`.
+* `kid.catalyst-rbac://preprod@cardano/<key>/7/3`
+  * A Signing key registered on the Cardano pre-production network.
+  * Role 7 - Rotation 3.
+  The Key for Role 7, and its third published rotation
+  (i.e., the fourth key published, the first is the initial key, plus 3 rotations following it).
+* `kid.catalyst-rbac://preprod@cardano/<key>/2/0#encrypt`
+  * A Public Encryption key registered on the Cardano pre-production network.
+  * Role 2 - Rotation 0.
+  The initially published Public Encryption Key for Role 2.
+* `kid.catalyst-rbac://midnight/<key>/0/1`
+  * A Signing key registered on the Midnight Blockchain Main network
+  * Role 0 - Rotation 1.
+  In this example, it is NOT the same as the `<key>`, as it identifies the first rotation after `<key>`.
+* `kid.catalyst-rbac://midnight/<key>/2/1#encrypt`
+  * A public encryption key registered on the Midnight Blockchain Main network.
+  * Role 2 - Rotation 1.
+
+## Rationale: how does this CIP achieve its goals?
+
+By creating a [URI] to identify keys,
+we allow the unambiguous and flexible identification of any RBAC Key that was used for any purpose.
+
+## Path to Active
+
+### Acceptance Criteria
+
+Working Implementation before Fund 14.
+
+### Implementation Plan
+
+Fund 14 project catalyst will deploy this scheme for Key Identification.
+
+## Copyright
+
+This document is licensed under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode).
+
+[URI]: https://datatracker.ietf.org/doc/html/rfc3986
+[Universal Resource Identifier]: https://datatracker.ietf.org/doc/html/rfc3986
+[RFC3986]: https://datatracker.ietf.org/doc/html/rfc3986
+[Base64 URL]: https://datatracker.ietf.org/doc/html/rfc4648#section-5

docs/src/architecture/08_concepts/signed_doc/spec.md

@@ -107,7 +107,7 @@ There can, and probably will, exist multiple versions of the same document.
 
 The `ver` is a [UUID] v7.
 
-The initial `ver` assigned the first time a Catalyst Signed Document is published will be identical to the [`id`](#id).
+The initial `ver` assigned the first time a Catalyst Signed Document is published **MUST** be identical to the [`id`](#id).
 Subsequent versions will retain the same [`id`](#id) and will create a new `ver`,
 following best practice for creating a new [UUID] v7.
 

rust/Earthfile

@@ -58,7 +58,7 @@ build:
         --args1="--libs=c509-certificate --libs=cardano-blockchain-types --libs=cardano-chain-follower --libs=hermes-ipfs" \
         --args2="--libs=cbork-cddl-parser --libs=cbork-abnf-parser --libs=cbork-utils --libs=catalyst-types" \
         --args3="--libs=catalyst-voting --libs=immutable-ledger --libs=vote-tx-v1 --libs=vote-tx-v2" \
-        --args4="--bins=cbork/cbork --libs=rbac-registration --libs=signed_doc" \
+        --args4="--bins=cbork/cbork --libs=rbac-registration --libs=catalyst-signed-doc" \
         --args5="--cov_report=$HOME/build/coverage-report.info" \
         --output="release/[^\./]+" \
         --junit="cat-libs.junit-report.xml" \

rust/cardano-blockchain-types/Cargo.toml

@@ -19,7 +19,6 @@ workspace = true
 
 [dependencies]
 pallas = { version = "0.30.1", git = "https://github.com/input-output-hk/catalyst-pallas.git", rev = "9b5183c8b90b90fe2cc319d986e933e9518957b3" }
-pallas-crypto = { version = "0.30.1", git = "https://github.com/input-output-hk/catalyst-pallas.git", rev = "9b5183c8b90b90fe2cc319d986e933e9518957b3" }
 # pallas-hardano = { version = "0.30.1", git = "https://github.com/input-output-hk/catalyst-pallas.git", rev = "9b5183c8b90b90fe2cc319d986e933e9518957b3" }
 cbork-utils = { version = "0.0.1", git = "https://github.com/input-output-hk/catalyst-libs.git", tag = "v0.0.11" }
 catalyst-types = { version = "0.0.1", git = "https://github.com/input-output-hk/catalyst-libs.git", tag = "r20250108-00" }

rust/cardano-blockchain-types/src/auxdata/metadatum.rs

@@ -2,11 +2,11 @@
 
 use std::sync::Arc;
 
+use catalyst_types::conversion::from_saturating;
 use dashmap::DashMap;
 use minicbor::Decode;
 
 use super::{metadatum_label::MetadatumLabel, metadatum_value::MetadatumValue};
-use crate::conversion::from_saturating;
 
 /// Transaction Metadata
 /// See: <https://github.com/IntersectMBO/cardano-ledger/blob/78b32d585fd4a0340fb2b184959fb0d46f32c8d2/eras/conway/impl/cddl-files/conway.cddl#L519>

rust/cardano-blockchain-types/src/conversion.rs

@@ -6,13 +6,40 @@
 //!
 //! Note: This fork terminology is different from fork in blockchain.
 
-use crate::conversion::from_saturating;
+use std::fmt;
+
+use catalyst_types::conversion::from_saturating;
 
 #[derive(Copy, Clone, Debug, PartialEq, Eq, Hash, PartialOrd)]
 /// Counter that is incremented every time there is a roll-back in live-chain.
 pub struct Fork(u64);
 
 impl Fork {
+    /// Fork for data that read from the blockchain during a backfill on initial sync
+    pub const BACKFILL: Self = Self(1);
+    /// Fork count for the first live block.
+    pub const FIRST_LIVE: Self = Self(2);
+    /// Fork for immutable data. This indicates that there is no roll-back.
+    pub const IMMUTABLE: Self = Self(0);
+
+    /// Is the fork for immutable data.
+    #[must_use]
+    pub fn is_immutable(&self) -> bool {
+        self == &Self::IMMUTABLE
+    }
+
+    /// Is the fork for backfill data.
+    #[must_use]
+    pub fn is_backfill(&self) -> bool {
+        self == &Self::BACKFILL
+    }
+
+    /// Is the fork for live data.
+    #[must_use]
+    pub fn is_live(&self) -> bool {
+        self >= &Self::FIRST_LIVE
+    }
+
     /// Convert an `<T>` to `Fork` (saturate if out of range).
     pub fn from_saturating<
         T: Copy
@@ -38,6 +65,17 @@ impl Fork {
     }
 }
 
+impl fmt::Display for Fork {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self.0 {
+            0 => write!(f, "IMMUTABLE"),
+            1 => write!(f, "BACKFILL"),
+            // For live forks: 2 maps to LIVE:1, 3 maps to LIVE:2 etc.
+            2..=u64::MAX => write!(f, "LIVE:{}", self.0 - 1),
+        }
+    }
+}
+
 impl From<u64> for Fork {
     fn from(value: u64) -> Self {
         Self(value)