068-tokens-roadmap.rst (8160B)
1 DD 68: Token Feature Roadmap 2 ############################ 3 4 *Status*: incomplete draft (2025-07-31) 5 6 Summary 7 ======= 8 9 This design document documents the roadmap for token types 10 supported by Taler. 11 12 Motivation 13 ========== 14 15 Plan for Wallet 16 =============== 17 18 Types of tokens: 19 20 * donations tokens (hard deadline: End of November) 21 22 * onboarding (1st donation) 23 24 * ask for tax payer id, add taxOfficeBaseUrl (only one per wallet) 25 * can be changed, but new donations will have a different tax payer ID 26 * store date with tax payer ID for merge 27 28 * reporting: per year, one QR code per: (taxPayerId, walletSalt, year) 29 30 * meta data per QR code: taxPayerId, walletSalt, year, taxOfficeBaseUrl 31 * out of scope: generate PDF 32 * listing: just show sum (per tax payer ID and year and salt), not individual tokens 33 34 * listing: there is separate listing for tokens 35 * delete: out of scope for now / future work 36 37 * subscription 38 39 * listing 40 41 * Expired tokens are deleted automatically after grace period (30 days). 42 * Consider not deleting the last token of a particular slug. 43 Maybe in the future, subscription tokens will have a link 44 to re-purchase them. 45 * No counter 46 * Show expiration date 47 * delete (with big fat warning) 48 49 * discount tokens 50 51 * listing (type and number, description) 52 * group by expiration date (if it exists) 53 * delete 54 55 * asset tokens (deadlines: end of March) 56 57 * listing (with number, no fractions possible, no expiration) 58 * background task: poll for share action, automatically execute the share action 59 60 * share action dividend: not supported for now 61 * share action voting: multiple in parallel possible, maybe show vote weight, have expiration date 62 * votes are grouped under the respective asset tokens 63 64 * voting action 65 66 * normally grouped under asset token ("history" for corporate actions) 67 * in notificiation state: vote directly or dismiss 68 * eventually, result is fetched and shown 69 70 * divident (initially out of scope) 71 72 * normally grouped under asset token ("history" for corporate actions) 73 * in notificiation state: dismiss, auto-dismiss after some time 74 75 76 Wallet UI Screenshots (Donau Integration) 77 ========================================= 78 79 Donau setup screen 80 ~~~~~~~~~~~~~~~~~~ 81 82 .. image:: ../screenshots/wallet/donau/donau-setup-android.png 83 :width: 50% 84 85 Balances view 86 ~~~~~~~~~~~~~ 87 88 .. image:: ../screenshots/wallet/donau/balances-android.png 89 :width: 50% 90 91 Donation statement 92 ~~~~~~~~~~~~~~~~~~ 93 94 .. image:: ../screenshots/wallet/donau/donation-statement-android.png 95 :width: 50% 96 97 Tax receipt available 98 ~~~~~~~~~~~~~~~~~~~~~ 99 100 .. image:: ../screenshots/wallet/donau/payment-android.png 101 :width: 50% 102 103 Tax receipt not available 104 ~~~~~~~~~~~~~~~~~~~~~~~~~ 105 106 .. image:: ../screenshots/wallet/donau/payment-notavailable-android.png 107 :width: 50% 108 109 Select Donau service 110 ~~~~~~~~~~~~~~~~~~~~ 111 112 .. image:: ../screenshots/wallet/donau/select-donau-android.png 113 :width: 50% 114 115 116 117 Plan for Merchant Backend 118 ========================= 119 120 Basic read-only contracts v1 support (release milestone 1.3, plan as of 2025-11-28): 121 122 * Rendering of orders (#10664): When the list of orders contains a v1 order 123 (for example created by the turnstile paywall), we should be able to render 124 it, instead of just saying "v1 unsupported". This is much less complex than 125 creating an order. We have the same fields as v0 plus choices (each choice 126 with its own inputs/outputs). It should be sufficient to use the existing 127 contract terms rendering and add the choices with inputs and outputs as a 128 list of sections. Since there is no specification yet for the contract terms 129 rendering, we just care about the raw information being accessible. 130 131 Creation of v1 contracts (release milestone 1.6, plan as of 2025-11-28): 132 133 * Creation of orders (#10665): There is 134 some preliminary design in the bug tracker, and once the time comes (1.6 135 milestone), we should do some sessions with her on the design. 136 * We might also think about ways that less technically experienced merchants 137 can use subscription/discount tokens, or could just leave this for integrations 138 like turnstile. 139 140 Improved and well-specified rendering of v1 contracts (release milestone >=1.6, plan as of 2025-11-28): 141 142 * We should have a DD describing the improved rendering of v1 contracts and 143 then implement this in the merchant and wallet. 144 * The merchant backend might also need to learn to show the preliminary contract terms 145 of orders that have not been claimed yet (#10615). 146 147 148 Plan for Donau 149 ============== 150 151 * Service exists 152 * Needs to packaged 153 154 155 User Experience 156 =============== 157 158 Donau MVP 159 ^^^^^^^^^ 160 161 **Donor / wallet user:** 162 163 1. User opens Taler wallet, goes to ``Settings -> Donations`` 164 2. In the initial state, user can enter a donau base URL and tax ID. 165 3. Subsequently, the ``Settings -> Donations`` screen shows: 166 167 * Currently configured donation authority 168 * Currently configured tax ID 169 * Navigation link ``Show donation statements`` 170 171 4. User makes a payment with a merchant that offers donation receipts. 172 If the merchant supports the same donau service as configured in the wallet, 173 the wallet UI shows some notice (e.g. ``This payment provides a donation receipt``). 174 175 5. User can view their current donation statement via ``Overview -> Donation statements``. 176 177 **Merchant:** 178 179 In the MVP, the merchant backend will be set up via the REST API, 180 we won't provide any SPA support. 181 182 Donau Next Iteration 183 ^^^^^^^^^^^^^^^^^^^^ 184 185 **Donor / wallet user:** 186 187 In the post-MVP iteration, we want to improve the onboarding experience. The 188 wallet should ask *during* a payment that supports a donation receipt if the 189 user wants to set up donation receipts. 190 191 As the merchant might offer multiple donau URLs (each for their own financial domain), 192 the user needs to be shown all possible donaus with their respective financial domain. 193 After choosing the donau, the user needs to enter their tax payer identifier. 194 195 **Merchant:** 196 197 In the post-MVP iteration, the merchant SPA should allow a merchant 198 to set up the donau integration. This includes the following steps: 199 200 1. The merchant registers a charity ID with the donau. 201 202 * The SPA should probably explain this process and 203 show the merchant public key, which needs to be given 204 to the donation authority for the charity registration process. 205 * The actual registration happens via a side channel (e-mail, postal, in 206 person, ...), there is no protocol for this. 207 * As a result of the registration, the merchant obtains a ``charity_id`` 208 209 2. The merchant SPA provides a configuration page for the 210 supported donation authorities, where the merchant can enter the donau base URL 211 and charity ID. 212 213 3. For each configured charity, there should be a details page 214 that shows the used and remaining donation amount. 215 216 4. When creating an order via the SPA, there should be an option 217 labled "this is a donation". 218 219 220 221 Test Plan 222 ========= 223 224 * Subscription/discount: blog.demo.taler.net 225 * Donations: donations.demo.taler.net 226 227 * Receipt validation: TBD 228 229 * Asset tokenization: TBD / will be deployed on demo via merchant 230 231 232 Donations: donations.demo.taler.net 233 =================================== 234 235 Donate page 236 ~~~~~~~~~~~~ 237 238 .. image:: ../screenshots/donau/donate-web.png 239 240 Payment method selection 241 ~~~~~~~~~~~~~~~~~~~~~~~~ 242 243 .. image:: ../screenshots/donau/payment-method-web.png 244 245 Taler Pay 246 ~~~~~~~~~ 247 248 .. image:: ../screenshots/donau/taler-pay.png 249 250 Receipt page 251 ~~~~~~~~~~~~ 252 253 .. image:: ../screenshots/donau/receipt-web.png 254 255 256 Donau Verify UI 257 =============== 258 259 Donau verification (input) 260 ~~~~~~~~~~~~~~~~~~~~~~~~~~ 261 262 .. image:: ../screenshots/donau/donau-verify.png 263 :width: 50% 264 265 Donau verification (verified) 266 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 267 268 .. image:: ../screenshots/donau/donau-verified.png 269 :width: 50% 270 271 272 Definition of Done 273 ================== 274 275 * Donau deployed in sandcastle 276 * donations in demo must use donau / contracttermsv1 277 * use separate app (prototype exists?) for verification of receipts 278 279 Discussion / Q&A 280 ================ 281 282 (This should be filled in with results from discussions on mailing lists / personal communication.)