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
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
|
/*
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_kyclogic_lib.h
* @brief server-side KYC API
* @author Christian Grothoff
*/
#ifndef TALER_KYCLOGIC_LIB_H
#define TALER_KYCLOGIC_LIB_H
#include <microhttpd.h>
#include <taler_exchangedb_plugin.h>
#include <taler_kyclogic_plugin.h>
/**
* Enumeration for our KYC user types.
*/
enum TALER_KYCLOGIC_KycUserType
{
/**
* KYC rule is for an individual.
*/
TALER_KYCLOGIC_KYC_UT_INDIVIDUAL = 0,
/**
* KYC rule is for a business.
*/
TALER_KYCLOGIC_KYC_UT_BUSINESS = 1
};
/**
* Enumeration of possible events that may trigger
* KYC requirements.
*/
enum TALER_KYCLOGIC_KycTriggerEvent
{
/**
* Customer withdraws coins.
*/
TALER_KYCLOGIC_KYC_TRIGGER_WITHDRAW = 0,
/**
* Merchant deposits coins.
*/
TALER_KYCLOGIC_KYC_TRIGGER_DEPOSIT = 1,
/**
* Wallet receives P2P payment.
*/
TALER_KYCLOGIC_KYC_TRIGGER_P2P_RECEIVE = 2,
/**
* Wallet balance exceeds threshold.
*/
TALER_KYCLOGIC_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
TALER_KYCLOGIC_kyc_trigger_from_string (
const char *trigger_s,
enum TALER_KYCLOGIC_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 *
TALER_KYCLOGIC_kyc_trigger2s (enum TALER_KYCLOGIC_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
TALER_KYCLOGIC_kyc_user_type_from_string (const char *ut_s,
enum TALER_KYCLOGIC_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 *
TALER_KYCLOGIC_kyc_user_type2s (enum TALER_KYCLOGIC_KycUserType ut);
/**
* Initialize KYC subsystem. Loads the KYC configuration.
*
* @param cfg configuration to parse
* @return #GNUNET_OK on success
*/
enum GNUNET_GenericReturnValue
TALER_KYCLOGIC_kyc_init (const struct GNUNET_CONFIGURATION_Handle *cfg);
/**
* Shut down the KYC subsystem.
*/
void
TALER_KYCLOGIC_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
(*TALER_KYCLOGIC_KycAmountIterator)(void *cls,
struct GNUNET_TIME_Absolute limit,
TALER_EXCHANGEDB_KycAmountCallback cb,
void *cb_cls);
/**
* Function called to iterate over KYC-relevant
* transaction thresholds amounts.
*
* @param cls closure, identifies the event type and
* account to iterate over events for
* @param threshold a relevant threshold amount
*/
typedef void
(*TALER_KYCLOGIC_KycThresholdIterator)(void *cls,
const struct TALER_Amount *threshold);
/**
* Call us on KYC processes satisfied for the given
* account. Must match the ``select_satisfied_kyc_processes`` of the exchange database plugin.
*
* @param cls the @e cls of this struct with the plugin-specific state
* @param h_payto account identifier
* @param spc function to call for each satisfied KYC process
* @param spc_cls closure for @a spc
* @return transaction status code
*/
typedef enum GNUNET_DB_QueryStatus
(*TALER_KYCLOGIC_KycSatisfiedIterator)(
void *cls,
const struct TALER_PaytoHashP *h_payto,
TALER_EXCHANGEDB_SatisfiedProviderCallback spc,
void *spc_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 ki callback that returns list of already
* satisfied KYC checks, implemented by ``select_satisfied_kyc_processes`` of the exchangedb
* @param ki_cls closure for @a ki
* @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 *
TALER_KYCLOGIC_kyc_test_required (enum TALER_KYCLOGIC_KycTriggerEvent event,
const struct TALER_PaytoHashP *h_payto,
TALER_KYCLOGIC_KycSatisfiedIterator ki,
void *ki_cls,
TALER_KYCLOGIC_KycAmountIterator ai,
void *ai_cls);
/**
* Iterate over all thresholds that are applicable
* to a particular type of @a event
*
* @param event tresholds to look up
* @param it function to call on each
* @param it_cls closure for @a it
*/
void
TALER_KYCLOGIC_kyc_iterate_thresholds (
enum TALER_KYCLOGIC_KycTriggerEvent event,
TALER_KYCLOGIC_KycThresholdIterator it,
void *it_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
TALER_KYCLOGIC_kyc_get_logic (const char *provider_section_name,
struct TALER_KYCLOGIC_Plugin **plugin,
struct TALER_KYCLOGIC_ProviderDetails **pd);
#endif
|
