chore(general): Merge branch 'main' into mve3

.config/dictionaries/project.dic

@@ -14,6 +14,7 @@ Arbritrary
 ARCHS
 ARGB
 Arissara
+asat
 asmjs
 asyncio
 asyncpg
@@ -241,6 +242,7 @@ rustflags
 rustfmt
 rustls
 rxdart
+ryszard-schossler
 saibatizoku
 Schemathesis
 Scripthash
@@ -286,7 +288,6 @@ trailings
 TXNZD
 txos
 Typer
-ryszard-schossler
 unawaited
 unchunk
 Unlogged

.github/ISSUE_TEMPLATE/test_plan.yml

@@ -1,5 +1,5 @@
 name: Test Plan
-description: Create a test plan
+description: Create a test plan.
 title: "[Test plan]: <title>"
 labels: ["testplan"]
 projects: ["/input-output-hk/102"]
@@ -11,18 +11,64 @@ body:
     validations:
       required: true
 
+  - type: textarea
+    attributes:
+      label: Stakeholders
+      description: Insert the relevant stakeholders that need to understand, review and approve the test plan
+      placeholder: |
+          | Name | Role | Approval |
+          |:-: |:-:|:-:|
+          |  |  | |
+    validations:
+      required: true
+
   - type: input
     attributes:
       label: Test plan document
       placeholder: https://input-output-hk.github.io/catalyst-voices/architecture/10_quality/testplans/template.md
-      description: A link to the test plan document.
+      description: A link to the test plan document if it is needed.
+    validations:
+      required: false
+
+  - type: textarea
+    attributes:
+      label: Requirements
+      description: Business requirements, insert links to relevant Github or JIRA tickets, list what platforms are supported, what will not be tested, etc
+    validations:
+      required: true
+
+  - type: textarea
+    attributes:
+      label: Acceptance criteria
+      description: List the acceptance criteria for this feature
+    validations:
+      required: true
+
+  - type: textarea
+    attributes:
+      label: Risks
+      description: Describe what risks can affect the accomplishment of the testplan. For example documentation is missing, not enough resources etc
+    validations:
+      required: true
+
+  - type: textarea
+    attributes:
+      label: Tools
+      description: Describe what tools will be needed for the testing, if new tools are needed to be developed
+    validations:
+      required: true
+
+  - type: textarea
+    attributes:
+      label: Test strategy
+      description: Describe the strategy for testing
     validations:
       required: true
 
   - type: textarea
     attributes:
       label: Test cases
-      description: The list of the test cases that are part of the test plan
+      description: The list of the test cases that are part of the test plan. Use the ACC framework [https://input-output-hk.github.io/catalyst-voices/architecture/10_quality/testplans/template/#acc-framework] to help you define testcases
       placeholder: |
         -[] https://github.com/input-output-hk/catalyst-voices/issues/1
         -[] https://github.com/input-output-hk/catalyst-voices/issues/1

catalyst-gateway/.gitignore

@@ -13,4 +13,5 @@ target/
 # Build artifacts
 cat-gateway.coverage.info
 cat-gateway.junit-report.xml
-cat-gateway-api.*
+cat-gateway-api.*
+expanded.rs

catalyst-gateway/Justfile

@@ -57,7 +57,22 @@ run-cat-gateway-mainnet: build-cat-gateway
     RUST_LOG="error,cat_gateway=debug,cardano_chain_follower=debug,mithril-client=debug" \
     ./target/release/cat-gateway run --log-level debug
 
-# Do the minimal work needed to test the schema generated by cat-gateway
-quick-schema-lint: build-cat-gateway
+# expand all macros and produce a single unified source file.
+expand-macros:
+    just bin/expand-macros
+
+# Generate the current openapi schema file locally.
+generate-openapi-schema: build-cat-gateway
     ./target/release/cat-gateway docs cat-gateway-api.json
-    docker run --rm -it -v $(pwd):/tmp stoplight/spectral:latest lint --ruleset "/tmp/tests/.oapi-v3.spectral.yml" "/tmp/cat-gateway-api.json"
+
+# Lint an openapi schema that has already been generated
+lint-generated-schema: 
+    docker run --rm -it -v $(pwd):/tmp stoplight/spectral:latest lint --ruleset "/tmp/tests/openapi-v3.0-lints/.spectral.yml" "/tmp/cat-gateway-api.json"
+
+# Lint an openapi schema that has already been generated locally.
+# Make sure before running this command, you have installed "spectral" locally.
+lint-generated-schema-local:
+    spectral lint --ruleset "./tests/openapi-v3.0-lints/.spectral.yml" "cat-gateway-api.json"
+
+# Do the minimal work needed to test the schema generated by cat-gateway
+quick-schema-lint: generate-openapi-schema lint-generated-schema

catalyst-gateway/bin/Cargo.toml

@@ -92,6 +92,7 @@ der-parser = "9.0.0"
 jsonschema = "0.26.1"
 bech32 = "0.11.0"
 const_format = "0.2.33"
+regex = "1.11.1"
 
 [dev-dependencies]
 proptest = "1.5.0"

catalyst-gateway/bin/Justfile

@@ -0,0 +1,12 @@
+# use with https://github.com/casey/just
+#
+# Developer convenience functions
+
+# cspell: words prereqs, commitlog, rustls, nocapture
+
+default:
+    @just --list --unsorted
+
+# expand all macros and produce a single unified source file.
+expand-macros:
+    cargo expand --release --bin cat-gateway > ../expanded.rs

catalyst-gateway/bin/src/service/api/cardano/cip36/endpoint.rs

@@ -0,0 +1,32 @@
+//! Implementation of the GET `/cardano/cip36` endpoint
+
+use std::time::Duration;
+
+use poem::http::HeaderMap;
+use tokio::time::sleep;
+
+use super::{
+    cardano::{self},
+    response, NoneOrRBAC, SlotNo,
+};
+use crate::service::common::{self};
+
+/// Process the endpoint operation
+pub(crate) async fn cip36_registrations(
+    _lookup: Option<cardano::query::stake_or_voter::StakeOrVoter>, _asat: Option<SlotNo>,
+    _page: common::types::generic::query::pagination::Page,
+    _limit: common::types::generic::query::pagination::Limit, _auth: NoneOrRBAC,
+    _headers: &HeaderMap,
+) -> response::AllRegistration {
+    // Dummy sleep, remove it
+    sleep(Duration::from_millis(1)).await;
+
+    // Todo: refactor the below into a single operation here.
+
+    // If _asat is None, then get the latest slot number from the chain follower and use that.
+    // If _for is not defined, use the stake addresses defined for Role0 in the _auth
+    // parameter. _auth not yet implemented, so put placeholder for that, and return not
+    // found until _auth is implemented.
+
+    response::Cip36Registration::NotFound.into()
+}

catalyst-gateway/bin/src/service/api/cardano/cip36/mod.rs

@@ -0,0 +1,140 @@
+//! CIP36 Registration Endpoints
+
+use ed25519_dalek::VerifyingKey;
+use poem::http::{HeaderMap, StatusCode};
+use poem_openapi::{param::Query, OpenApi};
+
+use self::cardano::slot_no::SlotNo;
+use super::Ed25519HexEncodedPublicKey;
+use crate::service::common::{
+    self,
+    auth::none_or_rbac::NoneOrRBAC,
+    tags::ApiTags,
+    types::cardano::{self},
+};
+
+pub(crate) mod endpoint;
+pub(crate) mod old_endpoint;
+pub(crate) mod response;
+
+/// Cardano Staking API Endpoints
+pub(crate) struct Api;
+
+#[OpenApi(tag = "ApiTags::Cardano")]
+impl Api {
+    /// CIP36 registrations.
+    ///
+    /// This endpoint gets the latest registration given either the voting key, stake
+    /// address, stake public key or the auth token.
+    ///
+    /// Registration can be the latest to date, or at a particular date-time or slot
+    /// number.
+    // Required To be able to look up for:
+    // 1. Voting Public Key
+    // 2. Cip-19 stake address
+    // 3. All - Hidden option and would need a hidden api key header (used to create a snapshot
+    //    replacement.)
+    // 4. Stake addresses associated with current Role0 registration (if none of the above
+    //    provided).
+    // If none of the above provided, return not found.
+    #[oai(
+        path = "/draft/cardano/registration/cip36",
+        method = "get",
+        operation_id = "cardanoRegistrationCip36"
+    )]
+    async fn get_registration(
+        &self, lookup: Query<Option<cardano::query::stake_or_voter::StakeOrVoter>>,
+        asat: Query<Option<cardano::query::AsAt>>,
+        page: Query<Option<common::types::generic::query::pagination::Page>>,
+        limit: Query<Option<common::types::generic::query::pagination::Limit>>,
+        /// No Authorization required, but Token permitted.
+        auth: NoneOrRBAC,
+        /// Headers, used if the query is requesting ALL to determine if the secret API
+        /// Key is also defined.
+        headers: &HeaderMap,
+    ) -> response::AllRegistration {
+        // Special validation for the `lookup` parameter.
+        // If the parameter is ALL, BUT we do not have a valid API Key, just report the parameter
+        // is invalid.
+        if let Some(lookup) = lookup.0.clone() {
+            if lookup.is_all(headers).is_err() {
+                return response::AllRegistration::unprocessable_content(vec![
+                    poem::Error::from_string(
+                        "Invalid Stake Address or Voter Key",
+                        StatusCode::UNPROCESSABLE_ENTITY,
+                    ),
+                ]);
+            }
+        }
+
+        endpoint::cip36_registrations(
+            lookup.0,
+            SlotNo::into_option(asat.0),
+            page.0.unwrap_or_default(),
+            limit.0.unwrap_or_default(),
+            auth,
+            headers,
+        )
+        .await
+    }
+
+    /// Get latest CIP36 registrations from stake address.
+    ///
+    /// This endpoint gets the latest registration given a stake address.
+    #[oai(
+        path = "/draft/cardano/cip36/latest_registration/stake_addr",
+        method = "get",
+        operation_id = "latestRegistrationGivenStakeAddr"
+    )]
+    async fn latest_registration_cip36_given_stake_addr(
+        &self,
+        /// Stake Public Key to find the latest registration for.
+        stake_pub_key: Query<Ed25519HexEncodedPublicKey>, // Validation provided by type.
+        /// No Authorization required, but Token permitted.
+        _auth: NoneOrRBAC,
+    ) -> old_endpoint::SingleRegistrationResponse {
+        let hex_key = stake_pub_key.0;
+        let pub_key: VerifyingKey = hex_key.into();
+
+        old_endpoint::get_latest_registration_from_stake_addr(&pub_key, true).await
+    }
+
+    /// Get latest CIP36 registrations from a stake key hash.
+    ///
+    /// This endpoint gets the latest registration given a stake key hash.
+    #[oai(
+        path = "/draft/cardano/cip36/latest_registration/stake_key_hash",
+        method = "get",
+        operation_id = "latestRegistrationGivenStakeHash"
+    )]
+    async fn latest_registration_cip36_given_stake_key_hash(
+        &self,
+        /// Stake Key Hash to find the latest registration for.
+        #[oai(validator(max_length = 66, min_length = 0, pattern = "[0-9a-f]"))]
+        stake_key_hash: Query<String>,
+        /// No Authorization required, but Token permitted.
+        _auth: NoneOrRBAC,
+    ) -> old_endpoint::SingleRegistrationResponse {
+        old_endpoint::get_latest_registration_from_stake_key_hash(stake_key_hash.0, true).await
+    }
+
+    /// Get latest CIP36 registrations from voting key.
+    ///
+    /// This endpoint returns the list of stake address registrations currently associated
+    /// with a given voting key.
+    #[oai(
+        path = "/draft/cardano/cip36/latest_registration/vote_key",
+        method = "get",
+        operation_id = "latestRegistrationGivenVoteKey"
+    )]
+    async fn latest_registration_cip36_given_vote_key(
+        &self,
+        /// Voting Key to find CIP36 registrations for.
+        #[oai(validator(max_length = 66, min_length = 66, pattern = "0x[0-9a-f]"))]
+        vote_key: Query<String>,
+        /// No Authorization required, but Token permitted.
+        _auth: NoneOrRBAC,
+    ) -> old_endpoint::MultipleRegistrationResponse {
+        old_endpoint::get_associated_vote_key_registrations(vote_key.0, true).await
+    }
+}