report-lib.h (10808B)
1 /* 2 This file is part of TALER 3 Copyright (C) 2016-2024 Taler Systems SA 4 5 TALER is free software; you can redistribute it and/or modify it under the 6 terms of the GNU Affero Public License as published by the Free Software 7 Foundation; either version 3, or (at your option) any later version. 8 9 TALER is distributed in the hope that it will be useful, but WITHOUT ANY 10 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 11 A PARTICULAR PURPOSE. See the GNU Affero Public License for more details. 12 13 You should have received a copy of the GNU Affero Public License along with 14 TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> 15 */ 16 /** 17 * @file auditor/report-lib.h 18 * @brief helper library to facilitate generation of audit reports 19 * @author Christian Grothoff 20 */ 21 #ifndef REPORT_LIB_H 22 #define REPORT_LIB_H 23 24 #include <gnunet/gnunet_util_lib.h> 25 #include "taler/taler_auditordb_plugin.h" 26 #include "taler/taler_exchangedb_lib.h" 27 #include "taler/taler_json_lib.h" 28 #include "taler/taler_bank_service.h" 29 #include "taler/taler_signatures.h" 30 31 /** 32 * Macro to use to access progress point value @a name. 33 */ 34 #define TALER_ARL_USE_PP(name) TAC_ ## name 35 36 /** 37 * Macro to use to declare progress point value @a name. 38 */ 39 #define TALER_ARL_DEF_PP(name) \ 40 uint64_t TALER_ARL_USE_PP (name) = 0 41 42 /** 43 * Macro to use to GET progress point value @a name from DB. 44 */ 45 #define TALER_ARL_GET_PP(name) \ 46 TALER_S (name), &TALER_ARL_USE_PP (name) 47 48 /** 49 * Macro to use to SET progress point value @a name in DB. 50 */ 51 #define TALER_ARL_SET_PP(name) \ 52 TALER_S (name), TALER_ARL_USE_PP (name) 53 54 /** 55 * Macro to use to access amount balance @a name. 56 */ 57 #define TALER_ARL_USE_AB(name) TAC_ ## name 58 59 /** 60 * Macro to use to declare amount balance @a name. 61 */ 62 #define TALER_ARL_DEF_AB(name) \ 63 struct TALER_Amount TALER_ARL_USE_AB (name) 64 65 /** 66 * Macro to use to GET amount balance @a name from DB. 67 */ 68 #define TALER_ARL_GET_AB(name) \ 69 TALER_S (name), &TALER_ARL_USE_AB (name) 70 71 /** 72 * Macro to use to SET amount balance @a name in DB. 73 */ 74 #define TALER_ARL_SET_AB(name) \ 75 TALER_S (name), &TALER_ARL_USE_AB (name) 76 77 78 /** 79 * Command-line option "-r": restart audit from scratch 80 */ 81 extern int TALER_ARL_restart; 82 83 /** 84 * Handle to access the exchange's database. 85 */ 86 extern struct TALER_EXCHANGEDB_Plugin *TALER_ARL_edb; 87 88 /** 89 * Which currency are we doing the audit for? 90 */ 91 extern char *TALER_ARL_currency; 92 93 /** 94 * How many fractional digits does the currency use? 95 */ 96 extern struct TALER_Amount TALER_ARL_currency_round_unit; 97 98 /** 99 * Our configuration. 100 */ 101 extern const struct GNUNET_CONFIGURATION_Handle *TALER_ARL_cfg; 102 103 /** 104 * Handle to access the auditor's database. 105 */ 106 extern struct TALER_AUDITORDB_Plugin *TALER_ARL_adb; 107 108 /** 109 * Master public key of the exchange to audit. 110 */ 111 extern struct TALER_MasterPublicKeyP TALER_ARL_master_pub; 112 113 /** 114 * Public key of the auditor. 115 */ 116 extern struct TALER_AuditorPublicKeyP TALER_ARL_auditor_pub; 117 118 /** 119 * REST API endpoint of the auditor. 120 */ 121 extern char *TALER_ARL_auditor_url; 122 123 /** 124 * REST API endpoint of the exchange. 125 */ 126 extern char *TALER_ARL_exchange_url; 127 128 /** 129 * At what time did the auditor process start? 130 */ 131 extern struct GNUNET_TIME_Absolute start_time; 132 133 134 /** 135 * Obtain information about a @a denom_pub. 136 * 137 * @param dh hash of the denomination public key to look up 138 * @param[out] issuep set to detailed information about @a denom_pub, NULL if not found, must 139 * NOT be freed by caller 140 * @return transaction status code 141 */ 142 enum GNUNET_DB_QueryStatus 143 TALER_ARL_get_denomination_info_by_hash ( 144 const struct TALER_DenominationHashP *dh, 145 const struct TALER_EXCHANGEDB_DenominationKeyInformation **issuep); 146 147 /** 148 * Obtain information about a @a denomination by its serial 149 * 150 * @param serial row id of the denomination to look up 151 * @param[out] issuep set to detailed information about @a denom_pub, NULL if not found, must 152 * NOT be freed by caller 153 * @return transaction status code 154 */ 155 enum GNUNET_DB_QueryStatus 156 TALER_ARL_get_denomination_info_by_serial ( 157 uint64_t serial, 158 const struct TALER_EXCHANGEDB_DenominationKeyInformation **issuep); 159 160 /** 161 * Obtain information about a @a denom_pub. 162 * 163 * @param denom_pub key to look up 164 * @param[out] issue set to detailed information about @a denom_pub, NULL if not found, must 165 * NOT be freed by caller 166 * @param[out] dh set to the hash of @a denom_pub, may be NULL 167 * @return transaction status code 168 */ 169 enum GNUNET_DB_QueryStatus 170 TALER_ARL_get_denomination_info ( 171 const struct TALER_DenominationPublicKey *denom_pub, 172 const struct TALER_EXCHANGEDB_DenominationKeyInformation **issue, 173 struct TALER_DenominationHashP *dh); 174 175 176 /** 177 * Type of an analysis function. Each analysis function runs in 178 * its own transaction scope and must thus be internally consistent. 179 * 180 * @param cls closure 181 * @return transaction status code 182 */ 183 typedef enum GNUNET_DB_QueryStatus 184 (*TALER_ARL_Analysis)(void *cls); 185 186 187 /** 188 * Perform addition of amounts. If the addition fails, logs 189 * a detailed error and calls exit() to terminate the process (!). 190 * 191 * Do not call this function directly, use #TALER_ARL_amount_add(). 192 * 193 * @param[out] sum where to store @a a1 + @a a2, set to "invalid" on overflow 194 * @param a1 first amount to add 195 * @param a2 second amount to add 196 * @param filename where is the addition called 197 * @param functionname name of the function where the addition is called 198 * @param line line number of the addition 199 */ 200 void 201 TALER_ARL_amount_add_ (struct TALER_Amount *sum, 202 const struct TALER_Amount *a1, 203 const struct TALER_Amount *a2, 204 const char *filename, 205 const char *functionname, 206 unsigned int line); 207 208 209 /** 210 * Perform addition of amounts. If the addition fails, logs 211 * a detailed error and calls exit() to terminate the process (!). 212 * 213 * @param[out] sum where to store @a a1 + @a a2, set to "invalid" on overflow 214 * @param a1 first amount to add 215 * @param a2 second amount to add 216 */ 217 #define TALER_ARL_amount_add(sum,a1,a2) \ 218 TALER_ARL_amount_add_ (sum, a1, a2, __FILE__, __FUNCTION__, __LINE__) 219 220 221 /** 222 * Perform subtraction of amounts where the result "cannot" be negative. If the 223 * subtraction fails, logs a detailed error and calls exit() to terminate the 224 * process (!). 225 * 226 * Do not call this function directly, use #TALER_ARL_amount_subtract(). 227 * 228 * @param[out] diff where to store (@a a1 - @a a2) 229 * @param a1 amount to subtract from 230 * @param a2 amount to subtract 231 * @param filename where is the addition called 232 * @param functionname name of the function where the addition is called 233 * @param line line number of the addition 234 */ 235 void 236 TALER_ARL_amount_subtract_ (struct TALER_Amount *diff, 237 const struct TALER_Amount *a1, 238 const struct TALER_Amount *a2, 239 const char *filename, 240 const char *functionname, 241 unsigned int line); 242 243 244 /** 245 * Perform subtraction of amounts where the result "cannot" be negative. If 246 * the subtraction fails, logs a detailed error and calls exit() to terminate 247 * the process (!). 248 * 249 * @param[out] diff where to store (@a a1 - @a a2) 250 * @param a1 amount to subtract from 251 * @param a2 amount to subtract 252 */ 253 #define TALER_ARL_amount_subtract(diff,a1,a2) \ 254 TALER_ARL_amount_subtract_ (diff, a1, a2, __FILE__, __FUNCTION__, \ 255 __LINE__) 256 257 258 /** 259 * Possible outcomes of #TALER_ARL_amount_subtract_neg(). 260 */ 261 enum TALER_ARL_SubtractionResult 262 { 263 /** 264 * Note that in this case no actual result was computed. 265 */ 266 TALER_ARL_SR_INVALID_NEGATIVE = -1, 267 268 /** 269 * The result of the subtraction is exactly zero. 270 */ 271 TALER_ARL_SR_ZERO = 0, 272 273 /** 274 * The result of the subtraction is a positive value. 275 */ 276 TALER_ARL_SR_POSITIVE = 1 277 }; 278 279 280 /** 281 * Perform subtraction of amounts. Negative results should be signalled by the 282 * return value (leaving @a diff set to 'invalid'). If the subtraction fails 283 * for other reasons (currency mismatch, normalization failure), logs a 284 * detailed error and calls exit() to terminate the process (!). 285 * 286 * Do not call this function directly, use #TALER_ARL_amount_subtract_neg(). 287 * 288 * @param[out] diff where to store (@a a1 - @a a2) 289 * @param a1 amount to subtract from 290 * @param a2 amount to subtract 291 * @param filename where is the addition called 292 * @param functionname name of the function where the addition is called 293 * @param line line number of the addition 294 * @return #TALER_ARL_SR_INVALID_NEGATIVE if the result was negative (and @a diff is now invalid), 295 * #TALER_ARL_SR_ZERO if the result was zero, 296 * #TALER_ARL_SR_POSITIVE if the result is positive 297 */ 298 enum TALER_ARL_SubtractionResult 299 TALER_ARL_amount_subtract_neg_ (struct TALER_Amount *diff, 300 const struct TALER_Amount *a1, 301 const struct TALER_Amount *a2, 302 const char *filename, 303 const char *functionname, 304 unsigned int line); 305 306 307 /** 308 * Perform subtraction of amounts. Negative results should be signalled by 309 * the return value (leaving @a diff set to 'invalid'). If the subtraction 310 * fails for other reasons (currency mismatch, normalization failure), logs a 311 * detailed error and calls exit() to terminate the process (!). 312 * 313 * @param[out] diff where to store (@a a1 - @a a2) 314 * @param a1 amount to subtract from 315 * @param a2 amount to subtract 316 * @return #TALER_ARL_SR_INVALID_NEGATIVE if the result was negative (and @a diff is now invalid), 317 * #TALER_ARL_SR_ZERO if the result was zero, 318 * #TALER_ARL_SR_POSITIVE if the result is positive 319 */ 320 #define TALER_ARL_amount_subtract_neg(diff,a1,a2) \ 321 TALER_ARL_amount_subtract_neg_ (diff, a1, a2, __FILE__, __FUNCTION__, \ 322 __LINE__) 323 324 325 /** 326 * Initialize DB sessions and run the analysis. 327 * 328 * @param ana analysis to run 329 * @param ana_cls closure for @a ana 330 * @return #GNUNET_OK on success 331 */ 332 enum GNUNET_GenericReturnValue 333 TALER_ARL_setup_sessions_and_run (TALER_ARL_Analysis ana, 334 void *ana_cls); 335 336 337 /** 338 * Setup global variables based on configuration. 339 * 340 * @param c configuration to use 341 * @return #GNUNET_OK on success 342 */ 343 enum GNUNET_GenericReturnValue 344 TALER_ARL_init (const struct GNUNET_CONFIGURATION_Handle *c); 345 346 347 /** 348 * Close connections to the database. 349 */ 350 void 351 TALER_ARL_done (void); 352 353 #endif