summaryrefslogtreecommitdiff
path: root/src/exchange/taler-exchange-httpd_kyc.h
blob: 1df264c15b2642b01f2b7d2368c1049fd9a2b5c9 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
/*
  This file is part of TALER
  Copyright (C) 2022 Taler Systems SA

  TALER is free software; you can redistribute it and/or modify it under the
  terms of the GNU Affero General Public License as published by the Free Software
  Foundation; either version 3, or (at your option) any later version.

  TALER is distributed in the hope that it will be useful, but WITHOUT ANY
  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.

  You should have received a copy of the GNU Affero General Public License along with
  TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
*/
/**
 * @file taler-exchange-httpd_kyc.h
 * @brief KYC API for the exchange
 * @author Christian Grothoff
 */
#ifndef TALER_EXCHANGE_HTTPD_KYC_H
#define TALER_EXCHANGE_HTTPD_KYC_H

#include <microhttpd.h>
#include "taler_exchangedb_plugin.h"
#include "taler_kyclogic_plugin.h"


/**
 * Enumeration for our KYC user types.
 */
enum TEH_KycUserType
{
  /**
   * KYC rule is for an individual.
   */
  TEH_KYC_UT_INDIVIDUAL = 0,

  /**
   * KYC rule is for a business.
   */
  TEH_KYC_UT_BUSINESS = 1
};


/**
 * Enumeration of possible events that may trigger
 * KYC requirements.
 */
enum TEH_KycTriggerEvent
{

  /**
   * Customer withdraws coins.
   */
  TEH_KYC_TRIGGER_WITHDRAW = 0,

  /**
   * Merchant deposits coins.
   */
  TEH_KYC_TRIGGER_DEPOSIT = 1,

  /**
   * Wallet receives P2P payment.
   */
  TEH_KYC_TRIGGER_P2P_RECEIVE = 2,

  /**
   * Wallet balance exceeds threshold.
   */
  TEH_KYC_TRIGGER_WALLET_BALANCE = 3

};


/**
 * Parse KYC trigger string value from a string
 * into enumeration value.
 *
 * @param trigger_s string to parse
 * @param[out] trigger set to the value found
 * @return #GNUNET_OK on success, #GNUNET_NO if option
 *         does not exist, #GNUNET_SYSERR if option is
 *         malformed
 */
enum GNUNET_GenericReturnValue
TEH_kyc_trigger_from_string (const char *trigger_s,
                             enum TEH_KycTriggerEvent *trigger);


/**
 * Convert KYC trigger value to human-readable string.
 *
 * @param trigger value to convert
 * @return human-readable representation of the @a trigger
 */
const char *
TEH_kyc_trigger2s (enum TEH_KycTriggerEvent trigger);


/**
 * Parse user type string into enumeration value.
 *
 * @param ut_s string to parse
 * @param[out] ut set to the value found
 * @return #GNUNET_OK on success, #GNUNET_NO if option
 *         does not exist, #GNUNET_SYSERR if option is
 *         malformed
 */
enum GNUNET_GenericReturnValue
TEH_kyc_user_type_from_string (const char *ut_s,
                               enum TEH_KycUserType *ut);


/**
 * Convert KYC user type to human-readable string.
 *
 * @param ut value to convert
 * @return human-readable representation of the @a ut
 */
const char *
TEH_kyc_user_type2s (enum TEH_KycUserType ut);


/**
 * Initialize KYC subsystem. Loads the KYC
 * configuration.
 *
 * @return #GNUNET_OK on success
 */
enum GNUNET_GenericReturnValue
TEH_kyc_init (void);


/**
 * Shut down the KYC subsystem.
 */
void
TEH_kyc_done (void);


/**
 * Function called to iterate over KYC-relevant
 * transaction amounts for a particular time range.
 * Called within a database transaction, so must
 * not start a new one.
 *
 * @param cls closure, identifies the event type and
 *        account to iterate over events for
 * @param limit maximum time-range for which events
 *        should be fetched (timestamp in the past)
 * @param cb function to call on each event found,
 *        events must be returned in reverse chronological
 *        order
 * @param cb_cls closure for @a cb
 */
typedef void
(*TEH_KycAmountIterator)(void *cls,
                         struct GNUNET_TIME_Absolute limit,
                         TALER_EXCHANGEDB_KycAmountCallback cb,
                         void *cb_cls);


/**
 * Check if KYC is provided for a particular operation. Returns the best
 * provider (configuration section name) that could perform the required
 * check.
 *
 * Called within a database transaction, so must
 * not start a new one.
 *
 * @param event what type of operation is triggering the
 *         test if KYC is required
 * @param h_payto account the event is about
 * @param ai callback offered to inquire about historic
 *         amounts involved in this type of operation
 *         at the given account
 * @param ai_cls closure for @a ai
 * @return NULL if no check is needed
 */
const char *
TEH_kyc_test_required (enum TEH_KycTriggerEvent event,
                       const struct TALER_PaytoHashP *h_payto,
                       TEH_KycAmountIterator ai,
                       void *ai_cls);


/**
 * Obtain the provider logic for a given @a provider_section_name.
 *
 * @param provider_section_name identifies a KYC provider process
 * @param[out] plugin set to the KYC logic API
 * @param[out] pd set to the specific operation context
 * @return #GNUNET_OK on success
 */
enum GNUNET_GenericReturnValue
TEH_kyc_get_logic (const char *provider_section_name,
                   struct TALER_KYCLOGIC_Plugin **plugin,
                   struct TALER_KYCLOGIC_ProviderDetails **pd);


#endif