commit cc56686c3253a73c026af974f78f0e9568662d0b
parent 703a71813e390f533993e4e414471c63b0958d97
Author: Christian Grothoff <grothoff@gnunet.org>
Date: Mon, 17 Aug 2026 20:53:43 +0200
initial draft
Diffstat:
1 file changed, 96 insertions(+), 1 deletion(-)
diff --git a/design-documents/100-shares.rst b/design-documents/100-shares.rst
@@ -9,16 +9,101 @@ CG has the lock on this.
Motivation
==========
+Taler can tokenize assets other than fiat-money or crypto-currencies.
+One asset class that could be particularly promising are shares in
+companies. This design document specifies how Taler could be used to
+tokenize shares and pay out dividends.
+
Requirements
============
+- emit shares for fiat money (raising capital), showing investor brief / shareholder agreement before purchase
+- sell shares for fiat money to new shareholders
+- buy shares for fiat money from existing shareholders
+- issue dividends from the business to shareholders
+- notify shareholders about business developments, such as shareholder meetings
+
+Enabling shareholders to vote (e-voiting) on business decisions is out of
+scope for this initial design and left for a future design document.
+
+
Proposed Solution
=================
+Shares are something a new frontend allows users to buy and sell
+(or the company to emit) using a traditional merchant backend for
+the cryptographic part:
+
+- add new token family "shares" in the merchant backend; it includes
+ new meta-data for wallets to learn about notifications and dividends
+ from the (new) frontend
+- share token families have a generation, like 2024 and 2025, where
+ the contract for selling 2024 tokens for 2025 tokens yields
+ the dividend (see below)
+- merchant backend tracks number of shares issued and bought back,
+ thus knows number of shares outstanding
+- buying shares is a regular v1 contract with share tokens as outputs
+ and Taler payments in digital cash are inputs; the token family
+ references the shareholder agreement (must not be forgotten with the
+ purchase details)
+- new frontend includes endpoints to send notifications to wallets
+ for issued shares, such as dividend notifications or shareholder
+ meeting announcements; wallets should request updates at a
+ frequency specified with the token family; all notifications are
+ ordered (numerically), with an endpoint to list all notifications
+ past a given serial ID, and another to download each of the
+ (historic) notifications; once issued, notifications never change;
+ notifications are signed by a long-term frontend key; note that
+ we probably want these announcements to be managed by the merchant
+ backend as a new feature: this way, all of the auditing can focus
+ just on the merchant backend
+- new frontend includes its own wallet; it is used to pay dividends;
+ wallets can request a contract to sell generation X shares for
+ generation X+1 shares (once a notification has been posted that
+ dividends for generation X shares are available). In that contract,
+ the wallet_data includes either a p2p-pull request that tells the
+ frontend where to pay the dividend (from its local wallet);
+ note that the frontend probably should handle the case where the
+ local wallet does not have the required balance and merely exports
+ the list of p2p-pull requests instead of executing them immediately
+- new frontend tracks order-book with buy and sell orders, allowing
+ share owners to indicate the number of shares they want to buy or
+ sell at a certain price; these bids must be *backed* by tokens
+ (money or shares) with signatures to buy or sell the respective
+ amount of stock at the given price; double-spending is NOT yet
+ detected when the order is made, but deferred up to the moment
+ where the order would be executed; here the frontend would use
+ a transient wallet: the buy order would be for an already
+ signed contract to buy shares, the sell order would include a
+ p2p-pull request to be satisfied; by giving the buyer the new
+ shares the frontend would be paid (into its bank account) and
+ could then (possibly delayed) use those funds to satisfy the
+ p2p-pull request from the seller; as above, a frontend-integrated
+ wallet may be able to immediately pay the p2p-pull requests (if
+ its balance is sufficient), or the p2p-pull requests are exported
+ to the administrator to be executed later
+- new frontend allows admin to emit new shares (picks best bids from
+ order-book at the deadline, possibly conditional upon top N-bids
+ exceeding minimum investment, or top N-bids being above minimum
+ price)
+- all requests are stored, and there is a new merchant auditor that
+ inspects the share transaction data and checks if all p2p-pull requests
+ have been paid out (the existing merchant backend reconciliation
+ logic should naturally already check the incoming deposits).
+ Note that the order book itself probably does NOT need to be in
+ the merchant backend, but we could keep it there as well (to keep
+ the new frontend "stateless"; in that case, we'd also want to track
+ the p2p-pull requests in the merchant backend)
+-
+
+
Test Plan
=========
-(If this DD concerns a new or changed feature, describe how it can be tested.)
+- backend logic to issue, sell, buy shares
+- pay out dividends
+- wallet-core and wallet-UI tests
+
Definition of Done
==================
@@ -30,9 +115,19 @@ flag or dev-mode flag.)
Alternatives
============
+- Using the exchange as the emitter of shares; not so good as it is
+ single-currency by design and not setup for dealing with purchases;
+ it might make p2p transfers easier, but regulation on trading is
+ different for shares and the mismatch is likely big enough that
+ not overloading the exchange code with is it is a good idea.
+
+
+
Drawbacks
=========
+
+
Discussion / Q&A
================
