taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

commit bc50cdfdcaa92a93759f59a3afffdaf59873db28
parent 4ff818c30cb225be4153dd1527b5d494361d016d
Author: Christian Grothoff <grothoff@gnunet.org>
Date:   Sat, 14 Nov 2026 21:25:03 +0100

update DD 100

Diffstat:
Mdesign-documents/100-shares.rst | 464+++++++++++++++++++++++++++++++++++++++----------------------------------------
1 file changed, 227 insertions(+), 237 deletions(-)

diff --git a/design-documents/100-shares.rst b/design-documents/100-shares.rst @@ -6,25 +6,30 @@ DD 100: Share Tokenization :DD shepherd: TBD :Historical contributors: Christian Grothoff :First published: 2026-08-09 -:Last substantive change: 2026-10-24 +:Last substantive change: 2026-11-14 Summary ======= -This document specifies how GNU Taler can tokenize shares in companies, how -such shares can be traded and how dividends are paid out. Share positions are -represented by share tokens held in the users' wallets, the merchant backend -provides the cryptographic machinery for the issuance, transfer and renewal of -those tokens, and the Taler exchange continues to process the -electronic-money payments used to buy shares and to receive dividends. - -For *registered* shares (*Namensaktien*) the design adds a share register that -keeps the authoritative record of the registered shareholders and of the number -of shares attributed to each of them. The register is maintained by the issuer -or by an operator designated by the issuer. Here the central principle is that -share tokens only represent share positions *technically*: a change of the -registered ownership of a share is processed by the share register. A transfer -request starts the registration process, and only a successful registration +This document specifies how GNU Taler can be used to support *registered* +shares (*Namensaktien*) for which a new *share register* keeps the +authoritative record of the registered shareholders and of the number of +shares attributed to each of them. The new *share register* provides the +cryptographic machinery for recording issuance, transfer, dividends and +e-voting based on shares held. The share register is maintained by the issuer +or by an operator designated by the issuer and modifying it is guarded by +requiring consent from an independent second party, the *share guard*. The +Taler exchange and merchant continue to process the electronic-money payments +used to buy or sell shares and to receive dividends. + +Private *shareholder keys* stored in the Taler wallets only serve to authorize +certain operations on the shares (such as withdrawing dividends, e-voting or +receiving information from the company). They also can serve as one of +*multiple authentication factors* required to authorize selling shares. Any +change of the registered ownership of a share is only effective once it has +been processed by the share register and authorized by the share guard. A +transfer request starts the process to update the register, and only a +successful registration in the register and approval by the share guard triggers the issuance of share tokens to the buyer. Motivation @@ -35,138 +40,137 @@ 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. -For registered shares, the system must additionally associate every share -position with an identified shareholder and keep a reliable record of the -changes of ownership. Simply moving bearer-style tokens from one wallet to -another would not by itself keep the wallet balances and the shareholder -register synchronized. The design therefore introduces an explicit -registration step into the share transfer protocol: this retains the -cryptographic and payment-processing mechanisms of GNU Taler while maintaining -a separate, auditable shareholder register. +For registered shares, the system must associate every share position with an +identified shareholder and keep a reliable record of the changes of ownership. +Simply moving bearer-style tokens from one wallet to another would not keep +the wallet balances and the shareholder register synchronized and not meet +legal registration requirement. Furthermore, the law requires an independent +entity to approve every update to the register. The design therefore does not +directly use the Taler cryptography to represent shares, but merely integrates +with it for buying and selling shares against cash, issuing new shares against +cash, paying out dividends and providing e-voting tokens for shareholder +decisions. Storing private shareholder keys in the Taler wallet is also convenient +as a way to provide an additional authentication factor that is backed up with +the regular wallet backup mechanisms. The actual implementation is provided +by new shareholder register and register guard components. Requirements ============ +User stories include: + - 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 +- sell of shares by a shareholder for fiat money to a new shareholders +- sell of shares by a shareholder for fiat money to existing shareholders +- buy shares for fiat money from existing shareholders as a new shareholder (with legitimization) +- buy shares for fiat money from existing shareholders as an existing shareholder (without legitimization) - issue dividends from the business to shareholders - notify shareholders about business developments, such as shareholder meetings +- issue shareholders e-voting tokens using blind signatures to enable voting on business decisions -Enabling shareholders to vote (e-voiting) on business decisions is out of +Enabling shareholders to vote (e-voting) on business decisions is out of scope for this initial design and left for a future design document. -For registered shares, the system must additionally be able to: - -- register shareholders following a successful identity verification -- record the allocation of newly issued shares to identified shareholders -- represent the registered share positions using share tokens -- initiate a transfer by presenting or transferring share tokens through the - share-transfer protocol -- verify the identity and the eligibility of the recipient before a transfer is - completed -- update the shareholder register before replacement share tokens are issued to - the recipient -- prevent the same share tokens from being used in multiple concurrent - transfers -- exchange share tokens of one generation for tokens of the next generation - while paying the corresponding dividend +The share register must in particular: + +- register shareholders following a successful legitimization (identity verification) step + and confirmation from the register guard +- record the allocation of newly issued shares to identified shareholders after + approval by the register guard +- initiate a transfer by reserving shares and complete the transfer to a + registered shareholder upon confirmation from the register guard; + the reservation must prevent the same shares from being used in + multiple concurrent transfers, and it must expire if the transfer does + not complete by some deadline; proof of payment by the buyer before + the deadline must be the last step +- record which shareholders have outstanding dividends for a particular + period, and updating the outstanding dividend amount atomically + when irrevokably paying the dividend +- record which shareholders have received ballots for a particular + vote - maintain an auditable history of share issuances, transfers, redemptions and dividend distributions -- reconcile the shareholder register, the issued share tokens and the completed - transactions Electronic-money payments continue to use the existing Taler exchange: share-specific functionality must not be implemented as a new asset class inside the exchange itself (see `Alternatives`_). + Proposed Solution ================= -Share Tokens, Frontend and Order Book -------------------------------------- +Components +---------- -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 +A share register service is introduced to a avoid overloading existing +components with share-specific responsibilities. The components have the +following responsibilities: + +- **share register**: the REST API and backend for share purchases, transfers and + shareholder information, including the relevant legal documents +- **share guard**: independent 2nd party receiving additional authorizations (MFA) + for share transfers; its consent is required for critical updates to the + share register (Note: find out what is legally critical and what is not!) +- **merchant backend**: purchase orders, payment references and the integration + with Taler's contracts +- **exchange**: the electronic-money operations, that is the purchase payments + and the dividend payouts + + +Share Tokens +------------ + +Shares are something the new share register allows users to buy and sell +(or the company to emit): + +- shareholder registration records legitimization data (at least + 3 factors) with both share register and share guard. Only registered + shareholders are allowed to transact with shares. One of the + factors is a private shareholder key stored in each wallet. + For some operations the private shareholder key may be configured + to suffice to authorize them. Some factors are exclusively used + by the share guard. +- share register tracks number of shares issued to each registered + shareholder +- buying shares is a regular contract with the contract terms + specifying the number of shares to be transferred; it must + additionally be signed by the private shareholder keys of buyer + and seller. + The contract only + becomes valid with the signatures of share register and share guard; + the share guard requires at least one more authentication factor + by the seller before providing its signature. + Share register and share guard update the register upon receiving + confirmation of the payment by the exchange during the reservation + window. The wallet of the buyer understands the share purchase + contract and only signs the deposit confirmations if all required + approvals are present and the time is significantly before the + end of the reservation window. +- the share register 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 + frequency specified in /config of the share register; 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 - -Notification endpoint ownership is therefore an open design decision: the -initial frontend-owned proposal and the merchant-backend alternative above -must be resolved before the API is specified. - -- 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) - -Registered Shares ------------------ - -For registered shares, the design separates three functions: - -- the share register maintains the authoritative record of the registered - shareholders and of their share positions -- the merchant backend and the share-token functionality handle the issuance, - the transfer requests and the renewal of share tokens -- the Taler exchange processes the electronic-money payments used to purchase - shares and to receive dividends + notifications are signed by a long-term share register key. +- wallets can use their private shareholder key to request dividend distribution. + Dividend distribution happens via a new type of contract where + either a p2p-pull request instructs to pay to a wallet, or where + a deposit request instructs the share register to deposit the funds + into a bank account. + Note that the share register should handle the case where it + does not directly make the payment and merely exports + the list of dividend payment requests (with signatures) to its operator. + It might be good if it could see if the operator satisfied the + request. +- the share-register allows admin to emit new shares; as always, + the share-guard must confirm. +- all requests are stored, and a single sequential timeline is + preserved by linking them blockchain-style, ensuring a single + top-level hash is enough to check consistency between + share-register and share-guard. + Shareholder Register -------------------- @@ -184,31 +188,73 @@ The register contains at least: - the registration date and the applicable effective date of each change - references to the transactions that caused each change +The register is authoritative for determining which shareholder is recorded as +holding a given number of shares. + +Every register change is recorded as an immutable event. Events include: + +- the initial share issuance +- the allocation of newly issued shares +- a transfer between shareholders +- a share buyback or cancellation +- a correction of a previously recorded event +- any other change affecting a shareholder's position + The register must support reconstructing the shareholder positions at an earlier point in time. The current position may be stored as a materialized balance, but every change must be traceable to a recorded register event. -The register is authoritative for determining which shareholder is recorded as -holding a given number of shares. Wallet balances must not be used as a -substitute for the register. +An event records the affected shareholders, the share class, the quantity, the +effective time, the recording time and the corresponding transaction +identifier. Corrections are represented by additional events rather than by +silently overwriting historical records. The service maintains the current +share positions derived from these events and provides the audit trail used for +reconciliation. + + +Shareholder MFA update +---------------------- + +Using a sufficient number of authorization mechanisms (possibly excluding the +private shareholder key) the share register and share guard allow the +shareholder to update the authorization mechanisms and to update their +legitimization data. This could in particular involve online legitimization +against the existing legitimization records. + +Todo: which authorization mechanisms should be implemented, what are good +thresholds for sufficient, are they configurable, and if so by the share +register/guard or by the shareholder individually? + Share Issuance -------------- -Shares are purchased through the new web frontend, which uses the merchant +Shares are purchased through the share register, which uses a merchant backend for the purchase order and for the payment. The buyer must have a -verified customer identity before a purchase can be completed. +verified shareholder identity before a purchase can be completed. For example, a customer purchases ten shares at EUR 100 each: -1. the frontend creates a purchase order for ten shares -2. the customer pays EUR 1000 using their Taler wallet -3. the merchant backend confirms the successful payment -4. the share register service verifies the purchase order, the customer - identity, the payment reference and the availability of shares -5. the service records the allocation of ten shares to the shareholder -6. only following the successful registration does the share-token - functionality issue ten share tokens into the buyer's wallet +0. the share register and share guard register the buyer, + with its shareholder public key and additional authorization + factors +1. share register and share guard confirm the sell authorization of + the issuer and reserve the shares from the issuer's quota +2. the share register creates a purchase order for ten shares, + including the public shareholder key of the buyer at a merchant backend +3. the customer pays EUR 1000 using their Taler wallet +4. the merchant backend confirms the successful payment +5. the share register and share guard verify the payment + and update the register, both arrive at the same hash + chain and sign the update; with both signatures, the update + is complete +6. only following the successful registration does the private + shareholder key of the buyer yield rights to the shares + +Note: do we need some logic to refund share +purchase prices if the share issuance date expired without the +transfer having been executed? + Share Transfer -------------- @@ -220,106 +266,50 @@ registered shares. The transfer protocol proceeds as follows: -1. the seller initiates a transfer of a given number of share tokens (sending - share tokens to another wallet, possibly as a share/money swap) -2. the share backend creates a unique transfer request and reserves the - corresponding tokens, or otherwise prevents their concurrent use -3. the recipient is identified and verified against the applicable eligibility +1. the recipient is identified and verified against the applicable eligibility requirements; the recipient's wallet must be bound to a verified customer identity (see `Identity and Privacy`_) -4. the share register service checks the seller's registered position, the +2. the seller initiates a transfer of a given number of shares +3. the share register service checks the seller's registered position, the requested quantity and any applicable transfer restrictions -5. if all required conditions are satisfied, the register records the change of - the shareholder attribution -6. the successful register event triggers the issuance of the corresponding - share tokens to the buyer -7. the transfer is marked as completed once the token issuance has been - confirmed - -For example, a shareholder holding ten shares transfers five shares to another -registered shareholder. Before the transfer, the register records ten shares -for the seller and none for the buyer; after the successful registration, it -records five shares for each of them. The seller retains five share tokens and -the buyer receives five newly issued share tokens. - -The buyer's tokens must not be issued before the register change has succeeded. -If the registration fails, the system must not issue tokens to the buyer; the -transfer request must then either be safely retried or cancelled, with any -reservation released according to the transfer protocol. The transfer process -must prevent double-spending and must ensure that two concurrent requests -cannot transfer the same registered share position twice. - -Share Register Events ---------------------- - -Every register change is recorded as an immutable event. Events include: - -- the initial share issuance -- the allocation of newly issued shares -- a transfer between shareholders -- a share buyback or cancellation -- a correction of a previously recorded event -- any other change affecting a shareholder's position - -An event records the affected shareholders, the share class, the quantity, the -effective time, the recording time and the corresponding transaction -identifier. Corrections are represented by additional events rather than by -silently overwriting historical records. The service maintains the current -share positions derived from these events and provides the audit trail used for -reconciliation. - -Dividends and Share Token Generations +4. the share backend creates a unique transfer request and *reserves* the + corresponding tokens, or otherwise prevents their concurrent use +5. the share guard also receives and authorization for the sale and adds + its own signature +6. an pay-pull request is created by the wallet of the seller with all of + the authorizations, including the public shareholder key of the buyer +7. the successful payment event (proof of purchase) transfers + the rights to the corresponding shares to the buyer; the buyer has + time to submit their proof of purchase until the reservation expires + to either the share register or the share guard +8. both the share register and the share + guard sign over the new share register chain head including a date and all of the + share transfers since the last generation. Once both signatures are present, + the register is considered *consistent*. Reservations only expire after + a new share register generation has achieved consistency and where the + respective reservation is either marked + as expired (date above expiration) or where the share transfer was executed. + + +Dividends and Ballot Token Generation ------------------------------------- -As described above, share tokens have a generation, such as 2026 or 2027, which -identifies the token series used for a particular dividend distribution period. -When a dividend becomes available, a notification identifying the relevant -generation and distribution is published, and a wallet holding tokens of -generation X may then request a contract to exchange those tokens for -generation X+1 tokens. - For registered shares, the share backend determines the number of shares eligible for the distribution and the corresponding dividend amount from the -shareholder register and the applicable entitlement rules, and not merely from -the number of tokens presented by the wallet. +shareholder register and the applicable entitlement rules. For example, a shareholder holds ten shares and is entitled to a dividend of -EUR 1 per share. The refresh then results in: - -- ten tokens of generation X being redeemed -- ten tokens of generation X+1 being issued -- EUR 10 being paid into the shareholder's wallet as ordinary Taler digital - cash - -The share position itself remains unchanged: only the token generation changes, -and the dividend is paid separately. The backend must ensure that each -dividend entitlement can be claimed only once. It must also handle transfers -and refresh requests consistently around the applicable dividend entitlement -date. - -Separation of Components ------------------------- +EUR 1 per share. The share register would then *increase* their dividend +entitlement by EUR 10, adding the new entitlement on top of one that might +be outstanding from a previous round. -The share register service is introduced precisely so that the exchange is not -overloaded with share-specific responsibilities. The components have the -following responsibilities: +The share position itself remains unchanged. The backend must ensure that +each dividend entitlement can be claimed only once. It must also handle +transfer requests consistently around the applicable dividend entitlement date +so that it is clear if shares are reserved for transfer before or after a +dividend distribution. -- **web frontend**: the user interface for share purchases, transfers and - shareholder information, including the relevant legal documents -- **merchant backend**: purchase orders, payment references and the integration - with Taler's contract and token mechanisms -- **share register service**: the shareholder records, the validation of - register changes, and the decision when a token issuance may proceed -- **share-token functionality**: issuance, redemption and refresh of share - tokens, and the coordination of the associated transfer and dividend - operations -- **exchange**: the electronic-money operations, that is the purchase payments - and the dividend payouts -The share register service and the share-token functionality may initially be -implemented as components of the same application, provided that their -responsibilities and their data integrity requirements remain clearly -separated. Data Model ---------- @@ -339,33 +329,32 @@ The implementation requires persistent records for: Every operation must have a unique identifier that connects the relevant payment, register event and token operation. + Identity and Privacy -------------------- The share register uses the customer identity established through the -applicable verification process. Wallet identifiers are associated with -customer identities through explicit backend records; a wallet identifier alone -must not be treated as proof of a shareholder's identity. +applicable verification process. Private shareholder keys in wallets are +associated with customer identities through explicit backend records; a wallet +identifier alone must not be treated as proof of a shareholder's authoriztion. Identity information should only be exposed to the components that require it. -The token protocols should use transaction references and other strictly +The protocols should use transaction references and other strictly necessary technical identifiers instead of unnecessarily distributing personal information. + Audit and Reconciliation ------------------------ -In addition to the merchant auditor described above, the system must support -reconciliation between: +The system must support reconciliation between: -- the shareholder register -- the issued and redeemed share tokens -- the pending and completed transfer requests -- the purchase payments +- the share register and the share guard +- the merchant/exchange payments for shares - the dividend entitlements and payouts -The reconciliation process must identify discrepancies such as missing token -issuances, incomplete transfers, duplicate processing attempts and unpaid +The reconciliation process must identify discrepancies such as +incomplete transfers, duplicate processing attempts and unpaid dividend obligations. A transfer or dividend operation must not be considered complete merely because @@ -400,9 +389,7 @@ Definition of Done corresponding share tokens - transfers initiate a registration process and do not issue tokens to the recipient before the registration succeeded -- failed transfers do not create additional share tokens -- a refresh replaces the previous token generation and pays the corresponding - dividend without changing the underlying share position +- failed transfers do not create shares - all operations can be audited and reconciled - the wallet and the merchant backend can recover safely from retries and interruptions @@ -415,6 +402,9 @@ Alternatives 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. +- Using the merchant backend as the emitter of shares; again, there + is a mismatch in requirements and combining the two is likely to + increase technical complexity without adequate gains. - Transferring bearer-style share tokens between wallets without a registration step; this does not provide the synchronization between wallet balances and the shareholder register that registered shares require.