extended README.md to doxygen mainpage and add to doxygen build

CMakeLists.txt

@@ -14,7 +14,7 @@ else()
     add_compile_options(-Wall -Wextra -pedantic)
 endif()
 
-project(oc-mint VERSION 0.0.1 LANGUAGES CXX)
+project(oc-issuer VERSION 0.0.2 LANGUAGES CXX)
 
 include(FetchContent)
 
@@ -64,10 +64,10 @@ find_package(Doxygen
              REQUIRED dot
              OPTIONAL_COMPONENTS mscgen dia)
 set(DOXYGEN_HAVE_DOT YES)
-doxygen_add_docs(
-    doc
-    src
-    COMMENT "Generate documentation"
+doxygen_add_docs( doc
+                  README.md 
+                  src
+		  COMMENT "Generate documentation"
 )
 
 # build common library
@@ -76,8 +76,8 @@ add_library(oc-mint-lib ${LIB_SOURCES})
 target_link_libraries(oc-mint-lib PUBLIC Crow::Crow)
 target_include_directories(oc-mint-lib PUBLIC ${expected_SOURCE_DIR}/include src) 
 
-add_executable(oc-mint src/main.cpp)
-target_link_libraries(oc-mint PRIVATE oc-mint-lib INTERFACE tl::expected::expected)
+add_executable(${PROJECT_NAME} src/main.cpp)
+target_link_libraries(${PROJECT_NAME} PRIVATE oc-mint-lib INTERFACE tl::expected::expected)
 
 ## these are unittests that can be run on any platform
 add_executable(tests  test/test_big_int.cpp test/test.cpp)

README.md

@@ -1,23 +1,47 @@
-![build](https://github.com/OpenCoin/oc-mint-cpp/actions/workflows/cmake.yaml/badge.svg)
+opencoin-issuer-cpp - a C++ OpenCoin Issuer REST-API implementation {#mainpage}
+=============================================================
 
-# oc mint sample
+![build](https://github.com/OpenCoin/opencoin-issuer-cpp/actions/workflows/cmake.yaml/badge.svg)
+[![Documentation](https://github.com/OpenCoin/opencoin-issuer-cpp/actions/workflows/doxygen-gh-pages.yml/badge.svg)](https://github.com/OpenCoin/opencoin-issuer-cpp/actions/workflows/doxygen-gh-pages.yml)
 
-this is a C++ implementation of the opencoin protocol 
-as mapping to some kind of REST interface 
+# opencoin issuer
 
-actually it is a work in progress.
+this is a C++ implementation of the [opencoin protocol](https://opencoin.org/0.4/OpenCoin.html)
+done as mapping to some kind of REST interface.
+
+As all issuer related interactions of the protocol follows a request/response mechanism we are able to map all of them to Http-Requests.
+
+We decided to use POST-Requests in all cases, 
+as the protocol uses JSON-formatted messages for requests.
+
+The following table gives an overview of the mapping of requests to URLs:
+
+| Request           | URL          | Response                      | C++ Interface Method                               |
+|:------------------|:-------------|:------------------------------|:---------------------------------------------------|
+| RequestCDDCSerial | /cddc/serial | ResponseCDDCSerial            | cdd.cdd_serial of Model::getCurrentCDDC() |
+| RequestCDDC       | /cddc        | ResponseCDDC                  | Model::getCurrentCDDC()                            |
+| RequestMKCs       | /mkcs        | ResponseMKCs                  | Model::getMKCs                                     |
+| RequestMint       | /mint        | ResponseMint                  | Model::mint                                        |
+| RequestRenew      | /renew       | ResponseMint or ResponseDelay | ?                                                  |
+| RequestResume     | /resume      | ResponseMint or ResponseDelay | ?                                                  |
+| RequestRedeem     | /redeem      | ResponseRedeem                | Model::redeem                                      |
+
+actually the implementation is a work in progress.
+
+## TODO
+
+- [ ] select crypto library
+   + https://en.wikipedia.org/wiki/Comparison_of_cryptography_libraries
++ [ ] blinding utilizing crypto++
++ [ ] integrate session and login to make transactions account based
++ [ ] bookkeeping for accounts
 
 ## Protocol Questions
 
 + What is signed as cdd - only the content of the cdd item with curly braces 
 or also the key?
 + the weighted URL as array has a different js encoding as other elements
-+ Clarify PSS usage (see https://crypto.stackexchange.com/questions/12707/usability-of-padding-scheme-in-blinded-rsa-signature)
-
-## TODO
-
-+ [ ] bigint type for big integers encoded as string
-+ [ ] blinding utilizing crypto++
++ Clarify PSS usage (see https://crypto.stackexchange.com/questions/12707/usability-of-padding-scheme-in-blinded-rsa-signature) 
 
 ### Blinding Notes
 

src/main.cpp

@@ -29,11 +29,11 @@ int main() {
 
   CROW_ROUTE(app, "/cddc/serial")
       .methods(crow::HTTPMethod::POST)([&model](const crow::request &request) {
-        auto req = RequestCDDSerial::from_string(request.body);
+        auto req = RequestCDDCSerial::from_string(request.body);
         if (!req) {
           return crow::response(crow::status::BAD_REQUEST);
         } else {
-          ResponseCDDSerial res;
+          ResponseCDDCSerial res;
           res.message_reference = req->message_reference;
 
           auto cddc = model->getCurrentCDDC();

src/model.cpp

@@ -104,7 +104,7 @@ crow::json::wvalue Response::to_json() const {
   return r;
 }
 
-crow::json::wvalue ResponseCDDSerial::to_json() const {
+crow::json::wvalue ResponseCDDCSerial::to_json() const {
   crow::json::wvalue r = Response::to_json();
   TO_JSON(cdd_serial);
 
@@ -112,8 +112,8 @@ crow::json::wvalue ResponseCDDSerial::to_json() const {
   return r;
 }
 
-tl::expected<RequestCDDSerial, eError>
-RequestCDDSerial::from_string(const std::string &str) {
+tl::expected<RequestCDDCSerial, eError>
+RequestCDDCSerial::from_string(const std::string &str) {
   auto json = crow::json::load(str);
   if (!json) {
     return tl::make_unexpected(eError::JSON_PARSE_ERROR);
@@ -122,7 +122,7 @@ RequestCDDSerial::from_string(const std::string &str) {
   } else if (json["type"] != "request cdd serial") {
     return tl::make_unexpected(eError::JSON_ERROR);
   } else {
-    RequestCDDSerial r;
+    RequestCDDCSerial r;
     r.message_reference = json["message_reference"].u();
     return r;
   }

src/model.hpp

@@ -25,30 +25,36 @@ struct WeightedUrl {
   crow::json::wvalue to_json() const;
 };
 
-/** currency description document */
+/** @brief currency description document 
+ *
+ * this structure describes a currency based on opencoin protocol. 
+ * It can be converted to json to provide the specified currency 
+ * description document. 
+ */
 struct CDD {
 
   std::string additional_info;
-  time_t cdd_expiry_date;//: 2023-07-22T15:45:53.164685
-  std::string  cdd_location;//: https://opencent.org,
-  size_t cdd_serial;//: 1,
-  time_t  cdd_signing_date;//: 2022-07-22T15:45:53.164685,
-  size_t  currency_divisor;//: 100,
-  std::string  currency_name;//: OpenCent,
-  std::vector<unsigned>  denominations;//: [1, 2, 5],
-  BigInt id;//: 23ed956e629ba35f0002eaf833ea436aea7db5c2,
+  time_t cdd_expiry_date;    /// expiry date of this document (e.g.
+                             ///2023-07-22T15:45:53.164685)
+  std::string cdd_location;  /// URL of location of this document (e.g
+                             ///https://opencent.org)
+  size_t cdd_serial;         /// serial number of currency description document
+  time_t cdd_signing_date;   /// date of signing this document (e.g.
+                             ///2022-07-22T15:45:53.164685)
+  size_t currency_divisor;   /// divisor used for coins of this currency
+  std::string currency_name; /// name of the currency (e.g. OpenCent)
+  std::vector<unsigned>
+      denominations; /// the available denominations of this currency
+  BigInt id;         /// an identity for this currency
 
-std::vector<WeightedUrl> info_service;
-  /* eCipherSuite*/ std::string issuer_cipher_suite; //: RSA-SHA256-PSS-CHAUM82,
-  PublicKey
-      issuer_public_master_key; //: {
-                                //  modulus:
-                                //  daaa63ddda38c189b8c49020c8276adbe0a695685a...,
-                                // public_exponent: 65537,
-                                // type: rsa public key
-  //},
+  std::vector<WeightedUrl> info_service;
+  /* eCipherSuite*/
+  std::string issuer_cipher_suite; /// the cipher suite used for this currencey
+                                   /// (currently only RSA-SHA256-PSS-CHAUM82 
+                                   ///  is supported)
+  PublicKey issuer_public_master_key; /// the public key of this currency
   std::vector<WeightedUrl> mint_service;
-  std::string protocol_version; //: https://opencoin.org/1.0,
+  std::string protocol_version; // e.g. https://opencoin.org/1.0
   std::vector<WeightedUrl> redeem_service;
   std::vector<WeightedUrl> renew_service;
 
@@ -100,14 +106,14 @@ struct Response {
   virtual crow::json::wvalue to_json() const;
 };
 
-struct RequestCDDSerial {
+struct RequestCDDCSerial {
   unsigned int message_reference; /// Client internal message reference.
                                   /// (Integer)
-  static tl::expected<RequestCDDSerial, eError>
+  static tl::expected<RequestCDDCSerial, eError>
   from_string(const std::string &str);
 };
 
-struct ResponseCDDSerial : Response {
+struct ResponseCDDCSerial : Response {
   unsigned int cdd_serial;
 
   crow::json::wvalue to_json() const override;
@@ -237,18 +243,63 @@ class Model {
 public:
   virtual ~Model(){};
 
+  /** 
+   * return the CurrencyDocumentDescription certifikate for a specific 
+   * serial version number of it.
+   * [see spec](https://opencoin.org/0.4/schemata.html#cddc)
+   * @return returns a pointer to the CDDC if successful, false otherwise
+   */
   virtual tl::expected<CDDC *, bool> getCDDC(unsigned int cdd_serial) = 0;
-  virtual tl::expected<CDDC *, bool> getCurrentCDDC() = 0;
 
+  /** 
+   * return the CurrencyDocumentDescription certifikate 
+   * [see spec](https://opencoin.org/0.4/schemata.html#cddc)
+   * @return returns a pointer to the CDDC if successful, false otherwise
+   */virtual tl::expected<CDDC *, bool> getCurrentCDDC() = 0;
+
+  /** 
+   * return the MintKey certificates for a given list of denominations 
+   * and mint key ids
+   *
+   * @param denominations 
+   * @param mint_key_ids 
+   *
+   * @return mint key certificates for given denominations and mint_key_ids
+   */
   virtual const std::vector<MintKeyCert>
   getMKCs(const std::vector<unsigned int> &denominations,
           const std::vector<BigInt> &mint_key_ids) = 0;
 
+
+  /** 
+   * returns the vector of blind signatures for a given vector of blinds
+   *
+   * @param transaction_reference reference to a transaction (send from client)
+   * @param blinds the vector of blinds to sign
+   *
+   * @return 
+   */
   virtual std::vector<BlindSignature>
   mint(std::string const& transaction_reference,
        const std::vector<Blind> &blinds) = 0;
+
+  /** 
+   * redeem valid coins into real money
+   *
+   * @param coins the coins to redeem
+   *
+   * @return true if successful, false on error
+   */
   virtual bool redeem(const std::vector<Coin> &coins) = 0;
 
+  /** 
+   * factory function returning a concrete backend for Opencoin API handling.
+   * based on backend_name a concrete backend will be returned 
+   * or in case of error null.
+   * @param backend_name 
+   *
+   * @return pointer to backend instance or null on invalid backend name
+   */
   static std::unique_ptr<Model> getModel(const std::string &backend_name);
 
 private:

test/test.cpp

@@ -15,32 +15,32 @@ TEST_CASE( "PublicKey::to_json", "[to_json]" ) {
   REQUIRE( json.keys().size() == 3 );
 }
 
-TEST_CASE("RequestCDDSerial::from_string", "[from_string]") {
+TEST_CASE("RequestCDDCSerial::from_string", "[from_string]") {
   // good case
   std::string good = "{"
                      "\"message_reference\": 100000,"
                      "\"type\": \"request cdd serial\""
                      "}";
 
-  auto res = RequestCDDSerial::from_string(good);
+  auto res = RequestCDDCSerial::from_string(good);
   REQUIRE(res.has_value() == true);
   REQUIRE(res->message_reference == 100000);
 
   // bad cases
-  res = RequestCDDSerial::from_string("");
+  res = RequestCDDCSerial::from_string("");
   REQUIRE(res.has_value() == false);
 
   // invalid type
-  res = RequestCDDSerial::from_string("{"
-                                      "\"message_reference\": 100000,"
-                                      "\"type\": \"request something wrong\""
-                                      "}");
+  res = RequestCDDCSerial::from_string("{"
+                                       "\"message_reference\": 100000,"
+                                       "\"type\": \"request something wrong\""
+                                       "}");
   REQUIRE(res.has_value() == false);
 
   // invalid attribute name
-  res = RequestCDDSerial::from_string("{"
-                                      "\"x_message_reference\": 100000,"
-                                      "}");
+  res = RequestCDDCSerial::from_string("{"
+                                       "\"x_message_reference\": 100000,"
+                                       "}");
   REQUIRE(res.has_value() == false);
 }