031-invoicing.rst (7257B)
1 DD 31: Invoicing 2 ################ 3 4 Summary 5 ======= 6 7 This document proposes new endpoints to support invoicing. 8 9 10 Motivation 11 ========== 12 13 We want to support a limited number of PULL payment requests where a purse is 14 created for a reserve without immediately requiring a purse fee. However, we 15 must prevent users from excessively creating purses (and uploading contracts) 16 as we do not want the exchange to be abused as a storage layer. Furthermore, 17 it would be good if the user sending a PULL payment request was properly 18 identified to the payer. 19 20 This design addresses bugs #7269 and #7274. 21 22 23 Requirements 24 ============ 25 26 * Effectively limit the number of open purses created by each individual 27 (or require purse fees if limit is exceeded). 28 29 * Ensure user has done KYC before doing a merge. 30 (Assuming the exchange does KYC at all.) 31 32 * Use information from KYC process to help payer identify payee. 33 34 * Reasonable UX and overall design impact. 35 36 * Wallets may want to pay for the reserve with coins 37 (reserve fresh, not created via bank transfer). 38 39 Unclear in the current proposal are: 40 41 * Here (and in other places!), the payment of the KYC 42 fee remains, eh, obscure. This should probably be 43 part of the KYC endpoints, and not for each 44 KYC-trigger. 45 46 * Proposed table structure does not properly capture 47 if user paid extra for more purses (I could open 48 for 3 years, then pay for 5x purses in year 1, but 49 should not automatically get 5x purses in years 2/3). 50 51 52 Proposed Solution 53 ================= 54 55 Allow users to tie their identity to a reserve "on demand" and when doing so 56 charge the ``account_fee``, bump the number of open purses threshold in the 57 ``reserves`` table and stop auto-closing of the reserve. This will ensure that 58 the users can withdraw the reserve balance into their wallet even after a 59 longer time period. This helps if the invoice is paid after a significant 60 delay. Introduce a way to force an immediate closure of a reserve, allowing 61 P2P reserve from invoices to be send to a bank account (this allows a wallet 62 to be used for convenient invoicing and not strictly require the wallet to 63 receive the funds). 64 65 The solution needs three new tables for: 66 67 * account creation data: 68 69 - serial 70 - timestamp 71 - signature affirming desire to create account 72 - KYC requirement row 73 74 * account creation payment data: 75 76 - serial (for replication) 77 - coin signature (affirming payment) 78 - amount contributed 79 - account creation link (serial row ID) 80 81 * reserve closure request data: 82 83 - serial (for replication) 84 - timestamp 85 - reserve signature 86 - target account payto:// URI 87 88 89 Specifically, the solution involves three new endpoints: 90 91 Opening reserves 92 ---------------- 93 94 * This new endpoint ``/reserve/$RID/open`` allows the user to 95 pay (for a year) to create a fixed number of purses and 96 to keep the reserve ``open`` (preventing auto-close); the 97 endpoint typically triggers a first (balance-independent) 98 KYC process (451) for a new KYC operation ``invoicing`` 99 (unless KYC is off). 100 101 * Upon completion of the ``invoicing`` KYC, the wallet 102 must again try to ``/open``. If successful, the wallet 103 may be asked to pay the annual fee (402). However, 104 usually the wallet should be aware of the fee, and already 105 have included a suitable deposit in the POST to the endpoint. 106 107 * Once the annual fee is paid, the now open 108 reserve is set to a non-zero counter of allowed concurrently 109 open purses, and the expiration time of the reserve is bumped 110 to the end of the time period for which the fee was paid. 111 112 Reserve Attestation 113 ------------------- 114 115 * This new endpoint ``/reserve/$RID/attest`` allows the user to 116 obtain exchange-signed KYC information about themselves. 117 This will basically be a list of (GANA standardized) attributes 118 and exchange signatures. The user can then choose which of 119 these attributes to include when invoicing. The available 120 set of attributes may differ depending on the KYC providers 121 configured and the attributes returned by the KYC logic. 122 We may choose to not use any fancy cryptography here, and 123 simply sign the different attributes individually. However, 124 we should always sign over the ``$RID`` to ensure that the 125 resulting signatures are meaningful. 126 127 * When receiving an invoice (PULL payment request), we may want to 128 mandate a certain minimal set of attributes that *should* always 129 be included, and if that is absent warn the receiver that the 130 sender of the invoice did not properly identify themselves. 131 132 * By making this a new endpoint, the client can re-request 133 the signatures on-demand. This is useful if we use the 134 EdDSA online signatures of the exchange, which likely expire 135 long before the user changes their attributes. 136 137 138 Closing reserves 139 ---------------- 140 141 * This new endpoint ``/reserve/$RID/close`` allows the user to 142 force-close a reserve that has not yet expired. This is useful 143 in case invoices have been paid into the reserve and the 144 user wants to get their money out. The ``close`` endpoint 145 must be provided with an appropriate payto://-URI as 146 reserves that were filled by P2P merge operations may not 147 already have an associated bank account (empty ``reserves_in`` 148 table). 149 150 151 Alternatives 152 ============ 153 154 We could require the target account to be already specified on ``open``. 155 However, that prevents people from invoicing that have no account (or we'd 156 have to allow ``payto://void/``, which then prevents people from closing later 157 if they got a bank account at a later stage). 158 159 We could allow an amount to be specified on ``close`` to partially wire the 160 funds in a reserve. However, reserves are not supposed to be used as bank 161 accounts (either to wallet *or* exceptionally to bank account, please!), and 162 this would conflict with the current implementation of the 163 **taler-exchange-closer**. So no amount is likely better for minimal 164 regulatory and implementation trouble. 165 166 Closing a reserve could also prevent the future use of the reserve for 167 invoicing. Right now, the specification allows this to continue, effectively 168 allowing users to repeatedly close an account to drain its funds to a bank 169 account instead of into a wallet. 170 171 We could mandate a fixed set of attributes. However, it is unclear whether all 172 exchanges will always have KYC providers enabled that offer any particular set 173 of attributes. It is conceivable that some exchanges may not run with any kind 174 of KYC, or just with phone-number validation, while others may require 175 government IDs but not phone numbers. So we can easily end up with completely 176 disjunct sets of attributes across operators. 177 178 We could not warn users if *insufficient* attributes were provided in an 179 invoice. However, that seems dangerous, especially as fake invoices are a 180 common attacker trick. 181 182 We could use attribute-based credentials (ABC) for the attestations. Benefits 183 and (complexity) drawbacks of such a change should be discussed with Martin. 184 185 186 Drawbacks 187 ========= 188 189 Quite a bit of work to implement. 190 191 192 Discussion / Q&A 193 ================ 194 195 (This should be filled in with results from discussions on mailing lists / personal communication.)