100-shares.rst (5639B)
1 DD 100: Share Tokenization 2 ########################## 3 4 Summary 5 ======= 6 7 8 Motivation 9 ========== 10 11 Taler can tokenize assets other than fiat-money or crypto-currencies. 12 One asset class that could be particularly promising are shares in 13 companies. This design document specifies how Taler could be used to 14 tokenize shares and pay out dividends. 15 16 Requirements 17 ============ 18 19 - emit shares for fiat money (raising capital), showing investor brief / shareholder agreement before purchase 20 - sell shares for fiat money to new shareholders 21 - buy shares for fiat money from existing shareholders 22 - issue dividends from the business to shareholders 23 - notify shareholders about business developments, such as shareholder meetings 24 25 Enabling shareholders to vote (e-voiting) on business decisions is out of 26 scope for this initial design and left for a future design document. 27 28 29 Proposed Solution 30 ================= 31 32 Shares are something a new frontend allows users to buy and sell 33 (or the company to emit) using a traditional merchant backend for 34 the cryptographic part: 35 36 - add new token family "shares" in the merchant backend; it includes 37 new meta-data for wallets to learn about notifications and dividends 38 from the (new) frontend 39 - share token families have a generation, like 2024 and 2025, where 40 the contract for selling 2024 tokens for 2025 tokens yields 41 the dividend (see below) 42 - merchant backend tracks number of shares issued and bought back, 43 thus knows number of shares outstanding 44 - buying shares is a regular v1 contract with share tokens as outputs 45 and Taler payments in digital cash are inputs; the token family 46 references the shareholder agreement (must not be forgotten with the 47 purchase details) 48 - new frontend includes endpoints to send notifications to wallets 49 for issued shares, such as dividend notifications or shareholder 50 meeting announcements; wallets should request updates at a 51 frequency specified with the token family; all notifications are 52 ordered (numerically), with an endpoint to list all notifications 53 past a given serial ID, and another to download each of the 54 (historic) notifications; once issued, notifications never change; 55 notifications are signed by a long-term frontend key; note that 56 we probably want these announcements to be managed by the merchant 57 backend as a new feature: this way, all of the auditing can focus 58 just on the merchant backend 59 - new frontend includes its own wallet; it is used to pay dividends; 60 wallets can request a contract to sell generation X shares for 61 generation X+1 shares (once a notification has been posted that 62 dividends for generation X shares are available). In that contract, 63 the wallet_data includes either a p2p-pull request that tells the 64 frontend where to pay the dividend (from its local wallet); 65 note that the frontend probably should handle the case where the 66 local wallet does not have the required balance and merely exports 67 the list of p2p-pull requests instead of executing them immediately 68 - new frontend tracks order-book with buy and sell orders, allowing 69 share owners to indicate the number of shares they want to buy or 70 sell at a certain price; these bids must be *backed* by tokens 71 (money or shares) with signatures to buy or sell the respective 72 amount of stock at the given price; double-spending is NOT yet 73 detected when the order is made, but deferred up to the moment 74 where the order would be executed; here the frontend would use 75 a transient wallet: the buy order would be for an already 76 signed contract to buy shares, the sell order would include a 77 p2p-pull request to be satisfied; by giving the buyer the new 78 shares the frontend would be paid (into its bank account) and 79 could then (possibly delayed) use those funds to satisfy the 80 p2p-pull request from the seller; as above, a frontend-integrated 81 wallet may be able to immediately pay the p2p-pull requests (if 82 its balance is sufficient), or the p2p-pull requests are exported 83 to the administrator to be executed later 84 - new frontend allows admin to emit new shares (picks best bids from 85 order-book at the deadline, possibly conditional upon top N-bids 86 exceeding minimum investment, or top N-bids being above minimum 87 price) 88 - all requests are stored, and there is a new merchant auditor that 89 inspects the share transaction data and checks if all p2p-pull requests 90 have been paid out (the existing merchant backend reconciliation 91 logic should naturally already check the incoming deposits). 92 Note that the order book itself probably does NOT need to be in 93 the merchant backend, but we could keep it there as well (to keep 94 the new frontend "stateless"; in that case, we'd also want to track 95 the p2p-pull requests in the merchant backend) 96 - 97 98 99 Test Plan 100 ========= 101 102 - backend logic to issue, sell, buy shares 103 - pay out dividends 104 - wallet-core and wallet-UI tests 105 106 107 Definition of Done 108 ================== 109 110 (Only applicable to design documents that describe a new feature. While the 111 DoD is not satisfied yet, a user-facing feature **must** be behind a feature 112 flag or dev-mode flag.) 113 114 Alternatives 115 ============ 116 117 - Using the exchange as the emitter of shares; not so good as it is 118 single-currency by design and not setup for dealing with purchases; 119 it might make p2p transfers easier, but regulation on trading is 120 different for shares and the mismatch is likely big enough that 121 not overloading the exchange code with is it is a good idea. 122 123 124 125 Drawbacks 126 ========= 127 128 129 130 Discussion / Q&A 131 ================ 132 133 (This should be filled in with results from discussions on mailing lists / personal communication.)