From 11c8265373360e9f2235f8f11ac16217d319648a Mon Sep 17 00:00:00 2001 From: Dovydas Joksas Date: Sat, 27 Jan 2024 11:15:29 +0000 Subject: [PATCH 01/16] improve split and fee descriptions --- value/value.md | 22 ++++++++-------------- 1 file changed, 8 insertions(+), 14 deletions(-) diff --git a/value/value.md b/value/value.md index d60e8e0c..f54eab6d 100644 --- a/value/value.md +++ b/value/value.md @@ -172,8 +172,8 @@ There is no limit on how many `valueRecipient` elements can be present in a give the `customKey`. - `type` (required) A slug that represents the type of receiving address that will receive the payment. - `address` (required) This denotes the receiving address of the payee. -- `split` (required) The number of shares of the payment this recipient will receive. -- `fee` (optional) If this attribute is not specified, it is assumed to be false. +- `split` (required) The number of shares or, if `fee` is `true`, the percentage of the payment that this recipient will receive. +- `fee` (optional) Indicates whether the recipient should instead receive a percentage amount off the top of each payment. If this attribute is not specified, it is assumed to be false.
@@ -196,18 +196,12 @@ Payments must be sent to a valid destination which is given in the `address` att depending on the underlying currency being used. -The `split` attribute denotes an amount of "shares" of the total payment that the recipient will receive when each timed -payment is made. -When a single `` is present, it should be assumed that the `split` for that recipient is 100%, -and the "split" should -be ignored. When multiple recipients are present, a share calculation (see below) should be made to determine how much -to send to each recipient's address. +The meaning of `split` depends on the value of `fee`: +- When `fee=true`, `split` denotes the percent value that should be taken off each transaction for the recipient. +- When `fee=false`, `split` denotes the number of "shares" for the recipient—splits among non-fee recipients represent the ratios in which the remaining amount (*after* the `fee=true` recipients receive their payments) must be distributed. -The `fee` attribute tells apps whether this split should be treated as a "fee", or a normal split. If this attribute is -true, then this split should be calculated -as a fee, meaning its percentage (as calculated from the shares) should be taken off the top of the entire transaction -amount. This is the preferred way for service -providers such as apps, hosting companies, API's and third-party value add providers to add their fee to a value block. +`fee=true` is the preferred way for service providers such as apps, hosting companies, APIs, and third-party value-add providers to add their fee to a value block. +Because when `fee=true`, `split` represents *percentage* value, the sum of splits for `fee=true` recipients cannot exceed 100. #### Custom Key/Value Pairs @@ -514,4 +508,4 @@ payload: "stream", "boost" and "auto". types of payments can contain textual messages (i.e. - a boostagram). * `auto` - This means the payment was an app initiated payment that recurs at a specific long-form interval such as weekly, monthly, yearly, etc. The user configures an interval and payment amount in the app and the app - then sends that amount at the specified time when each interval passes. \ No newline at end of file + then sends that amount at the specified time when each interval passes. From b144274d1374db0923dc3d5e01fd234aec5158eb Mon Sep 17 00:00:00 2001 From: Dovydas Joksas Date: Sat, 27 Jan 2024 11:31:20 +0000 Subject: [PATCH 02/16] describe general-case calculation --- value/value.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/value/value.md b/value/value.md index f54eab6d..b5e0e9a6 100644 --- a/value/value.md +++ b/value/value.md @@ -225,9 +225,18 @@ the player to your app, and for which nothing already exists, add your own. ### Payment calculation -The interval payment calculation is: +A given recipient will receive +``` +Payment amount * Interval payout * Interval count +``` + +`Payment amount` is calculated differently depending on whether `fee` is `true` of `false`. + +For `fee=false` recipients $X_1, X_2, \ldots, X_m$ with splits $x_1, x_2, \ldots, x_m$ and `fee=true` recipients $Y_1, Y_2, \ldots, Y_n$ with splits $y_1, y_2, \ldots, y_n$: + +1. Firstly, `fee=true` recipients $Y_1, Y_2, \ldots, Y_n$ will receive $y_1\\%$, $y_2\\%$, $\ldots$, $y_n\\%$ of the transaction. +2. Then, the remaining amount will be distributed among `fee=false` recipients $X_1, X_2, \ldots, X_m$ in the ratio $x_1 : x_2 : \ldots : x_m$. - (Number of shares / Share total) * Interval payout * Interval count To calculate payouts, let's take the following value block as an example: From 0d4898c8a25656ec2a493ed82a933546f40d9732 Mon Sep 17 00:00:00 2001 From: Dovydas Joksas Date: Sat, 27 Jan 2024 11:54:47 +0000 Subject: [PATCH 03/16] improve example #1 for payment calculation --- value/value.md | 63 +++++++++++++++++++++----------------------------- 1 file changed, 26 insertions(+), 37 deletions(-) diff --git a/value/value.md b/value/value.md index b5e0e9a6..d3290f19 100644 --- a/value/value.md +++ b/value/value.md @@ -237,26 +237,25 @@ For `fee=false` recipients $X_1, X_2, \ldots, X_m$ with splits $x_1, x_2, \ldots 1. Firstly, `fee=true` recipients $Y_1, Y_2, \ldots, Y_n$ will receive $y_1\\%$, $y_2\\%$, $\ldots$, $y_n\\%$ of the transaction. 2. Then, the remaining amount will be distributed among `fee=false` recipients $X_1, X_2, \ldots, X_m$ in the ratio $x_1 : x_2 : \ldots : x_m$. - -To calculate payouts, let's take the following value block as an example: +#### Example 1: no fees, splits add up to 100 ```xml ``` -This block designates three payment recipients. On each timed payment interval, the total payment will be split into 3 -smaller -payments according to the shares listed in the split for each recipient. So, in this case, if the listener decided to -pay 100 sats per minute for listening -to this podcast, then once per minute the "Host" would be sent 50 sats, the "Co-Host" would be sent 40 sats and the -"Producer" would be sent 10 sats - all to their respective lightning node addresses using the "keysend" protocol. - -If, instead of a 50/40/10 (total of 100) split, the splits were given as 190/152/38 (total of 380), the respective -payment amounts each minute would still -be 50 sats, 40 sats and 10 sats because the listener chose to pay 100 sats per minute, and the respective shares (as a -percentage of the total) would remain the same. - -On a 190/152/38 split, each minute the payment calculation would be: - -- Interval payout: 100 sats +This block designates three payment recipients. +On each timed payment interval, the total payment will be split into 3 smaller payments according to the `split` of each recipient. +Because there are no `fee=true` recipients, step 1 of the calculation can be skipped—the splits represent the ratios in which the payment should be divided. +I.e., for recipients `A`, `B`, and `C`, the payment should be divided in the ratio $50:40:10$: +- `A` will receive $\dfrac{50}{50 + 40 + 10} = 0.5 = 50\\%$ of the payment +- `B` will receive $\dfrac{40}{50 + 40 + 10} = 0.4 = 40\\%$ of the payment +- `C` will receive $\dfrac{10}{50 + 40 + 10} = 0.1 = 10\\%$ of the payment -- Share total: 380 +In this case, because splits add up to 100 (that is, $50 + 40 + 10 = 100$), the splits happen to correspond to the percentage values that each recipient will receive. +However, in general, it should never be assumed or expected that splits add up to 100. - - Recipient #1 gets a payment of: 50 sats (190 / 380 * 100) - - Recipient #2 gets a payment of: 40 sats (152 / 380 * 100) - - Recipient #3 gets a payment of: 10 sats (38 / 380 * 100) +Suppose that the listener chose to pay 300 sats per minute. Each minute, the payment calculation would be: -If an app chooses to only make a payout once every 30 minutes of listening/watching, the calculation would be the same -after multiplying -the per-minute payment by 30: +Interval payout: **300 sats** + +- Recipient `A` gets a payment of 150 sats (calculated using $300 \cdot \dfrac{50}{50 + 40 + 10} = 150$) +- Recipient `B` gets a payment of 120 sats (calculated using $300 \cdot \dfrac{40}{50 + 40 + 10} = 120$) +- Recipient `C` gets a payment of 30 sats (calculated using $300 \cdot \dfrac{10}{50 + 40 + 10} = 30$) -- Interval payout: 3000 sats (100 * 30) +If an app chooses to only make a payout once every 5 minutes of listening/watching, the calculation would be the same after multiplying the per-minute payment by 5: -- Shares total: 380 +Interval payout: **1500 sats** (calculated using $5 \cdot 300 = 1500$) - - Recipient #1 gets a payment of: 1500 sats (190 / 380 * 3000) - - Recipient #2 gets a payment of: 1200 sats (152 / 380 * 3000) - - Recipient #3 gets a payment of: 300 sats (38 / 380 * 3000) +- Recipient `A` gets a payment of 750 sats (calculated using $1500 \cdot \dfrac{50}{50 + 40 + 10} = 750$) +- Recipient `B` gets a payment of 600 sats (calculated using $1500 \cdot \dfrac{40}{50 + 40 + 10} = 600$) +- Recipient `C` gets a payment of 150 sats (calculated using $1500 \cdot \dfrac{10}{50 + 40 + 10} = 150$) -As shown above, the once per minute calculation does not have to actually be sent every minute. A longer payout period -can be chosen. But, -the once-per-minute nature of the payout still remains in order for listeners and creators to have an easy way to -measure and calculate how much -they will spend and charge. +As shown above, the once per minute calculation does not have to actually be sent every minute. +A longer payout period can be chosen. But, the once-per-minute nature of the payout still remains in order for listeners and creators to have an easy way to measure and calculate how much they will spend and charge.

From a419d2540706a1f61153896d42732407bf26d8e8 Mon Sep 17 00:00:00 2001 From: Dovydas Joksas Date: Sat, 27 Jan 2024 12:05:37 +0000 Subject: [PATCH 04/16] add example where splits don't add up to 100 --- value/value.md | 47 ++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 46 insertions(+), 1 deletion(-) diff --git a/value/value.md b/value/value.md index d3290f19..de14ad35 100644 --- a/value/value.md +++ b/value/value.md @@ -274,7 +274,8 @@ I.e., for recipients `A`, `B`, and `C`, the payment should be divided in the rat In this case, because splits add up to 100 (that is, $50 + 40 + 10 = 100$), the splits happen to correspond to the percentage values that each recipient will receive. However, in general, it should never be assumed or expected that splits add up to 100. -Suppose that the listener chose to pay 300 sats per minute. Each minute, the payment calculation would be: +Suppose that the listener chose to pay 300 sats per minute. +Each minute, the payment calculation would be: Interval payout: **300 sats** @@ -293,6 +294,50 @@ Interval payout: **1500 sats** (calculated using $5 \cdot 300 = 1500$) As shown above, the once per minute calculation does not have to actually be sent every minute. A longer payout period can be chosen. But, the once-per-minute nature of the payout still remains in order for listeners and creators to have an easy way to measure and calculate how much they will spend and charge. +#### Example 2: no fees, splits don't add up to 100 + +```xml + + + + + + +``` + +Again, there are no `fee=true` recipients, so step 1 of the calculation can be skipped. +The splits represent the ratios in which the payment should be divided. +I.e., for recipients `A`, `B`, and `C`, the payment should be divided in the ratio $100:99:1$: +- `A` will receive $\dfrac{100}{100 + 99 + 1} = 0.5 = 50\\%$ of the payment +- `B` will receive $\dfrac{99}{100 + 99 + 1} = 0.495 = 49.5\\%$ of the payment +- `C` will receive $\dfrac{1}{100 + 99 + 10} = 0.005 = 0.5\\%$ of the payment + +This example demonstrates why splits should not be required to add up to 100—it allows for recipients to receive payments that are not just integer percent values. +In this specific case, it allows `B` to receive $49.5\\%$ and `C` to receive $0.5\\%$. + +Suppose that the listener chose to send a 1000-sat boost, which the app decides to distribute immediately among the recipients: + +Interval payout: **1000 sats** + +- Recipient `A` gets a payment of 500 sats (calculated using $1000 \cdot \dfrac{100}{100 + 99 + 1} = 500$) +- Recipient `B` gets a payment of 495 sats (calculated using $1000 \cdot \dfrac{99}{100 + 99 + 1} = 495$) +- Recipient `C` gets a payment of 5 sats (calculated using $1000 \cdot \dfrac{1}{100 + 99 + 1} = 5$) +

From ee7116793213de3b8415341153a55f48769578ef Mon Sep 17 00:00:00 2001 From: Dovydas Joksas Date: Sat, 27 Jan 2024 12:23:07 +0000 Subject: [PATCH 05/16] add example with fees --- value/value.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/value/value.md b/value/value.md index de14ad35..24915044 100644 --- a/value/value.md +++ b/value/value.md @@ -338,6 +338,56 @@ Interval payout: **1000 sats** - Recipient `B` gets a payment of 495 sats (calculated using $1000 \cdot \dfrac{99}{100 + 99 + 1} = 495$) - Recipient `C` gets a payment of 5 sats (calculated using $1000 \cdot \dfrac{1}{100 + 99 + 1} = 5$) +#### Example 3: recipients with `fee=true` + +```xml + + + + + + + +``` + +In this case, there are two `fee=true` recipients, so the calculation will have to be done in two steps: + +1. `C` will receive $16\\%$ and `D` will receive $4\\%$ off the top of each payment. +2. The rest of the payment (i.e., $100\\% - 16\\% - 4\\% = 80\\%$) will be distributed among `A` and `B` in the ratio $101 : 99$. + +Suppose that the listener chose to send a 2500-sat boost, which the app decides to distribute immediately among the recipients: + +Interval payout: **2500 sats** + +1. `fee=true` recipients are paid first: + - Recipient `C` gets a payment of 400 sats (calculated using $2500 \cdot 0.16 = 400$) + - Recipient `D` gets a payment of 100 sats (calculated using $2500 \cdot 0.04 = 100$) +2. After that, `fee=false` recipients distribute the remaining amount of 2000 sats (calculated using $2500 - 400 - 100 = 2000$) + - Recipient `A` gets a payment of 1010 sats (calculated using $2000 \cdot \dfrac{101}{101 + 99} = 1010$) + - Recipient `B` gets a payment of 990 sats (calculated using $2000 \cdot \dfrac{99}{101 + 99} = 990$) +

From 6ec1a02ae81fc6d335c33ce353cb6385c9386cd5 Mon Sep 17 00:00:00 2001 From: Dovydas Joksas Date: Sat, 27 Jan 2024 12:38:17 +0000 Subject: [PATCH 06/16] improve clarity --- value/value.md | 47 +++++++++++++++++++++++------------------------ 1 file changed, 23 insertions(+), 24 deletions(-) diff --git a/value/value.md b/value/value.md index 24915044..e5c58972 100644 --- a/value/value.md +++ b/value/value.md @@ -9,8 +9,7 @@ ## Purpose Here we describe an additional "block" of XML that gives podcasters (and other media creators) a way to receive direct -payments from their audience in response to the action of viewing or listening to a created work. Utilizing so called " -Layer 2" +payments from their audience in response to the action of viewing or listening to a created work. Utilizing so called "Layer-2" cryptocurrency networks like Lightning, and possibly other digital currency mechanisms, near real-time micropayments can be directly sent from listener or viewer to the creator without the need for a payment processor or other "middle men". @@ -25,18 +24,19 @@ the use of fiat currency, if there is an API that is capable of interfacing as a ## Play to Pay This system can be thought of as Play-to-pay, rather than the traditional Pay-to-play paywall approach. When a -media listener (such as within a podcast app) presses the play button on an episode who's feed contains a value +media listener (such as within a podcast app) presses the play button on an episode whose feed contains a value block, a compatible app will be expected to begin streaming micro-payments to the designated recipients on a time interval that makes sense for the app. The amount of each payment can be any amount the listener chooses, including -zero. If the listener chooses not to pay to listen to this media, then the app can ignore the value block of that feed. +zero. Alternatively, the listener can send one-time payments (referred to as "boosts" in this document). +If the listener chooses not to pay to listen to this media, then the app can ignore the value block of that feed.
## Payment Intervals -The "time interval" for calculating payments is **always 1 minute**. However, the actual interval between when payments +The "time interval" for calculating streaming payments is **always 1 minute**. However, the actual interval between when payments are sent can be longer. The interval should be chosen with a few factors in mind such as connectivity (is the app -currently on-line?), transaction fees (batch payments together to reduce fee percentage), cryptocurrency network load +currently online?), transaction fees (batch payments together to reduce fee percentage), cryptocurrency network load (can the given crypto network or API support this payment rate?). No matter what the chosen time interval for the actual transaction, the calculation should be done on a once-per-minute @@ -54,8 +54,8 @@ that make up the total runtime of the content, thus all payment calculations are ## Elements -There are two elements that make up what we refer to as the "value block". They are a parent element that specifies the -currency to use, and one or more child elements that specify who to pay using the currency and protocol described by the +There are two elements that make up what we refer to as the "value block". They are a parent element (``) that specifies the +currency to use, and one or more child elements (``) that specify who to pay using the currency and protocol described by the parent.
@@ -95,17 +95,17 @@ This element can exist at either the `` or `` level. #### Explanation: -Using Lightning as an example, the `type` would be "lightning". Various possible `type` values will be kept +Using Lightning as an example, the `type` would be `"lightning"`. Various possible `type` values will be kept in a slug list [here](valueslugs.txt). This is the only type currently in active use. Others are under development and will be added to the list as they see some measure of adoption, or at least a working example to prove viability. The `method` attribute is used to indicate a sub-protocol to use within the given `type`. Again, returning to -Lightning as an example, the `method` would be "keysend". Normally, a Lightning payment requires an invoice -to be generated by the payee in order to fulfill a transaction. The "keysend" protocol of Lightning allows payments +Lightning as an example, the `method` would be `"keysend"`. Normally, a Lightning payment requires an invoice +to be generated by the payee in order to fulfill a transaction. The `"keysend"` protocol of Lightning allows payments to be streamed to what is, essentially, an open invoice. Other cryptocurrencies may have a similar protocol that -would be used here. If not, a value of "default" should be given. +would be used here. If not, a value of `"default"` should be given. -The "suggested" amount is just that. It's a suggestion, and must be changeable by the user to another value, or +The `"suggested"` amount is just that. It's a suggestion, and must be changeable by the user to another value, or to zero. The suggested amount depends on the payment protocol being used. For instance, with Lightning on the Bitcoin network, the amount can be as low as one millisatoshi, expressed as `0.00000000001` BTC. @@ -172,7 +172,7 @@ There is no limit on how many `valueRecipient` elements can be present in a give the `customKey`. - `type` (required) A slug that represents the type of receiving address that will receive the payment. - `address` (required) This denotes the receiving address of the payee. -- `split` (required) The number of shares or, if `fee` is `true`, the percentage of the payment that this recipient will receive. +- `split` (required) If `fee=false`, the number of shares for the recipient; if `fee=true`, the percentage of the payment that the recipient will receive. - `fee` (optional) Indicates whether the recipient should instead receive a percentage amount off the top of each payment. If this attribute is not specified, it is assumed to be false.
@@ -185,7 +185,7 @@ simple like podcaster chooses to donate a percentage of their incoming funds to a charity. -The `type` denotes what type of receiving entity this is. For instance, with lightning this would typically be "node". +The `type` denotes what type of receiving entity this is. For instance, with lightning this would typically be `"node"`. This would indicate that the `address` attribute for this recipient is a Lightning node that is capable of directly receiving incoming keysend payments. Valid values for @@ -206,7 +206,7 @@ Because when `fee=true`, `split` represents *percentage* value, the sum of split #### Custom Key/Value Pairs The `customKey` and `customValue` pair can be used (especially for the Lighning Network) to help a receiving application -route or process payments that have all arrived at one node. +route or process payments that have all arrived at a single node. The idea is that Podcast Index will parse and store and all client apps will always send a `customKey:customValue` pair if these are found in the Value Block. @@ -394,11 +394,11 @@ Interval payout: **2500 sats** ### Supported Currencies and Protocols -The value block is designed to be flexible enough to handle most any cryptocurrency, and even fiat currencies with a +The value block is designed to be flexible enough to handle any cryptocurrency, and even fiat currencies with a given API that exposes a compatible process. -Currently, development is centered mostly on [Lightning](https://github.com/lightningnetwork) using the "keysend" +Currently, development is centered mostly on [Lightning](https://github.com/lightningnetwork) using the `"keysend"` method. Keysend allows for push based payments without the recipient needing to generate an invoice to receive them. Another method to send spontaneous payments via Lightning is AMP, atomic @@ -414,8 +414,8 @@ widely implemented as of now. For the `` tag, the following attributes MUST be used: -- `type` (required): "lightning" -- `method` (required): "keysend" or "amp" +- `type` (required): `"lightning"` +- `method` (required): `"keysend"` or `"amp"` - `suggested` (optional): A float representing a BTC amount. e.g. 0.00000005000 is 5 Sats. @@ -431,7 +431,7 @@ utilized as follows: - `type`: "node" - `method`: "keysend" or "amp" -- `customKey`: \ +- `customKey`: \ - `customValue`: \ - `address`: \ - `split`: \ @@ -453,8 +453,7 @@ When sending a payment containing application specific data, the client must use This is a live, working example of a Lightning keysend value block in production. It designates four recipients for payment - two podcast hosts at 49 and 46 shares respectively, a producer working on per episode chapter creation who gets a 5 share, -and -a single share (effectively 1%) fee to the Podcastindex.org API. +and 1% to the Podcastindex.org API. Since the value block is defined at the `` level, it applies to every podcast episode. ```xml @@ -506,7 +505,7 @@ payment `method` to `amp`: ``` -##### Example: `` Override +##### Example: `` Override To set up different payment splits for individual episodes, a value block has to be defined on the `` level. This will override the value settings set on From 04d06c3e8d9b3c3a328f1505ee70e2add54710e0 Mon Sep 17 00:00:00 2001 From: Dovydas Joksas Date: Sat, 27 Jan 2024 12:43:57 +0000 Subject: [PATCH 07/16] minor improvements to clarity --- value/value.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/value/value.md b/value/value.md index e5c58972..e2e4932f 100644 --- a/value/value.md +++ b/value/value.md @@ -227,7 +227,7 @@ the player to your app, and for which nothing already exists, add your own. A given recipient will receive ``` -Payment amount * Interval payout * Interval count +(Payment amount) * (Interval payout) * (Interval count) ``` `Payment amount` is calculated differently depending on whether `fee` is `true` of `false`. @@ -365,7 +365,7 @@ Interval payout: **1000 sats** @@ -384,7 +384,7 @@ Interval payout: **2500 sats** 1. `fee=true` recipients are paid first: - Recipient `C` gets a payment of 400 sats (calculated using $2500 \cdot 0.16 = 400$) - Recipient `D` gets a payment of 100 sats (calculated using $2500 \cdot 0.04 = 100$) -2. After that, `fee=false` recipients distribute the remaining amount of 2000 sats (calculated using $2500 - 400 - 100 = 2000$) +2. After that, `fee=false` recipients get the remaining amount of 2000 sats (calculated using $2500 - 400 - 100 = 2000$): - Recipient `A` gets a payment of 1010 sats (calculated using $2000 \cdot \dfrac{101}{101 + 99} = 1010$) - Recipient `B` gets a payment of 990 sats (calculated using $2000 \cdot \dfrac{99}{101 + 99} = 990$) From 2907aa133a7fff3b3ad5df7fc66f283d65729832 Mon Sep 17 00:00:00 2001 From: Dovydas Joksas Date: Sat, 27 Jan 2024 12:47:00 +0000 Subject: [PATCH 08/16] update valueRecipient attributes' description in main doc --- docs/1.0.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/docs/1.0.md b/docs/1.0.md index a590fd00..bbf6dc78 100644 --- a/docs/1.0.md +++ b/docs/1.0.md @@ -830,8 +830,8 @@ and what it is capable of. belongs to the `customKey`. - **type** (required) A slug that represents the type of receiving address that will receive the payment. - **address** (required) This denotes the receiving address of the payee. - - **split** (required) The number of shares of the payment this recipient will receive. - - **fee** (optional) If this attribute is not specified, it is assumed to be false. + - **split** (required) If `fee=false`, the number of shares for the recipient; if `fee=true`, the percentage of the payment that the recipient will receive. + - **fee** (optional) Indicates whether the recipient should instead receive a percentage amount off the top of each payment. If this attribute is not specified, it is assumed to be false. ### Examples ```xml @@ -840,19 +840,19 @@ and what it is capable of. name="Alice (Podcaster)" type="node" address="02d5c1bf8b940dc9cadca86d1b0a3c37fbe39cee4c7e839e33bef9174531d27f52" - split="40" + split="45" /> ``` - -



## Medium ``

From 87284605b6dfe2c7446d027748db5887e661b585 Mon Sep 17 00:00:00 2001 From: Dovydas Joksas Date: Sat, 27 Jan 2024 17:47:14 +0000 Subject: [PATCH 09/16] clarify interval count and batching --- value/value.md | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/value/value.md b/value/value.md index e2e4932f..23f27cfe 100644 --- a/value/value.md +++ b/value/value.md @@ -225,16 +225,20 @@ the player to your app, and for which nothing already exists, add your own. ### Payment calculation -A given recipient will receive +When all combined, together the recipients will receive ``` -(Payment amount) * (Interval payout) * (Interval count) +(Batch payout) = (Interval count) * (Unit amount) ``` -`Payment amount` is calculated differently depending on whether `fee` is `true` of `false`. +`Unit amount` refers to one of the following +- either the amount of a one-time payment (with `Interval count` usually being 1) +- or the amount being streamed per minute (with `Interval count` referring to the interval in minutes at which the payouts are made) + +How `Batch payout` is divided between the recipients depends on their `split` and `fee` values. For `fee=false` recipients $X_1, X_2, \ldots, X_m$ with splits $x_1, x_2, \ldots, x_m$ and `fee=true` recipients $Y_1, Y_2, \ldots, Y_n$ with splits $y_1, y_2, \ldots, y_n$: -1. Firstly, `fee=true` recipients $Y_1, Y_2, \ldots, Y_n$ will receive $y_1\\%$, $y_2\\%$, $\ldots$, $y_n\\%$ of the transaction. +1. Firstly, `fee=true` recipients $Y_1, Y_2, \ldots, Y_n$ will receive $y_1\\%$, $y_2\\%$, $\ldots$, $y_n\\%$ of the total batch payout. 2. Then, the remaining amount will be distributed among `fee=false` recipients $X_1, X_2, \ldots, X_m$ in the ratio $x_1 : x_2 : \ldots : x_m$. #### Example 1: no fees, splits add up to 100 @@ -274,10 +278,9 @@ I.e., for recipients `A`, `B`, and `C`, the payment should be divided in the rat In this case, because splits add up to 100 (that is, $50 + 40 + 10 = 100$), the splits happen to correspond to the percentage values that each recipient will receive. However, in general, it should never be assumed or expected that splits add up to 100. -Suppose that the listener chose to pay 300 sats per minute. -Each minute, the payment calculation would be: +Suppose that the listener chose to pay 300 sats per minute with the app sending out the payments each minute. Then: -Interval payout: **300 sats** +Batch payout: **300 sats** - Recipient `A` gets a payment of 150 sats (calculated using $300 \cdot \dfrac{50}{50 + 40 + 10} = 150$) - Recipient `B` gets a payment of 120 sats (calculated using $300 \cdot \dfrac{40}{50 + 40 + 10} = 120$) @@ -285,7 +288,7 @@ Interval payout: **300 sats** If an app chooses to only make a payout once every 5 minutes of listening/watching, the calculation would be the same after multiplying the per-minute payment by 5: -Interval payout: **1500 sats** (calculated using $5 \cdot 300 = 1500$) +Batch payout: **1500 sats** (calculated using $5 \cdot 300 = 1500$) - Recipient `A` gets a payment of 750 sats (calculated using $1500 \cdot \dfrac{50}{50 + 40 + 10} = 750$) - Recipient `B` gets a payment of 600 sats (calculated using $1500 \cdot \dfrac{40}{50 + 40 + 10} = 600$) @@ -332,7 +335,7 @@ In this specific case, it allows `B` to receive $49.5\\%$ and `C` to receive $0. Suppose that the listener chose to send a 1000-sat boost, which the app decides to distribute immediately among the recipients: -Interval payout: **1000 sats** +Batch payout: **1000 sats** - Recipient `A` gets a payment of 500 sats (calculated using $1000 \cdot \dfrac{100}{100 + 99 + 1} = 500$) - Recipient `B` gets a payment of 495 sats (calculated using $1000 \cdot \dfrac{99}{100 + 99 + 1} = 495$) @@ -379,7 +382,7 @@ In this case, there are two `fee=true` recipients, so the calculation will have Suppose that the listener chose to send a 2500-sat boost, which the app decides to distribute immediately among the recipients: -Interval payout: **2500 sats** +Batch payout: **2500 sats** 1. `fee=true` recipients are paid first: - Recipient `C` gets a payment of 400 sats (calculated using $2500 \cdot 0.16 = 400$) From d38d6b54e26662615751fcd317da60b67cbd10e1 Mon Sep 17 00:00:00 2001 From: Dovydas Joksas Date: Sat, 27 Jan 2024 20:15:23 +0000 Subject: [PATCH 10/16] replace `Unit amount` with `Listener payment` Co-authored-by: Eric P --- value/value.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/value/value.md b/value/value.md index 23f27cfe..b690ebbe 100644 --- a/value/value.md +++ b/value/value.md @@ -227,7 +227,7 @@ the player to your app, and for which nothing already exists, add your own. When all combined, together the recipients will receive ``` -(Batch payout) = (Interval count) * (Unit amount) +(Batch payout) = (Listener payment) * (Interval count) ``` `Unit amount` refers to one of the following From 2fd1f94a8bfb0747c662d13fc0e5b624c8cecac7 Mon Sep 17 00:00:00 2001 From: Dovydas Joksas Date: Sat, 27 Jan 2024 20:16:05 +0000 Subject: [PATCH 11/16] Update description of `Listener payment` and `Interval count` Co-authored-by: Eric P --- value/value.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/value/value.md b/value/value.md index b690ebbe..3b95566e 100644 --- a/value/value.md +++ b/value/value.md @@ -230,9 +230,9 @@ When all combined, together the recipients will receive (Batch payout) = (Listener payment) * (Interval count) ``` -`Unit amount` refers to one of the following -- either the amount of a one-time payment (with `Interval count` usually being 1) -- or the amount being streamed per minute (with `Interval count` referring to the interval in minutes at which the payouts are made) +`Listener payment` and `Interval count` refer to one of the following scenarios: +- either the amount of a one-time payment made by the listener (with `Interval count` usually being 1) +- or the amount being streamed per-minute by the listener (with `Interval count` referring to the interval in minutes at which payments are sent by their client) How `Batch payout` is divided between the recipients depends on their `split` and `fee` values. From 63d7c26416b4d24077e33fecd9b9eab0cab74732 Mon Sep 17 00:00:00 2001 From: Dovydas Joksas Date: Sat, 27 Jan 2024 20:18:42 +0000 Subject: [PATCH 12/16] Exchange X and Y for fee=false and fee=true Co-authored-by: Eric P --- value/value.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/value/value.md b/value/value.md index 3b95566e..ef838f05 100644 --- a/value/value.md +++ b/value/value.md @@ -236,10 +236,10 @@ When all combined, together the recipients will receive How `Batch payout` is divided between the recipients depends on their `split` and `fee` values. -For `fee=false` recipients $X_1, X_2, \ldots, X_m$ with splits $x_1, x_2, \ldots, x_m$ and `fee=true` recipients $Y_1, Y_2, \ldots, Y_n$ with splits $y_1, y_2, \ldots, y_n$: +For `fee=true` recipients $X_1, X_2, \ldots, X_m$ with splits $x_1, x_2, \ldots, x_m$ and `fee=false` recipients $Y_1, Y_2, \ldots, Y_n$ with splits $y_1, y_2, \ldots, y_n$: -1. Firstly, `fee=true` recipients $Y_1, Y_2, \ldots, Y_n$ will receive $y_1\\%$, $y_2\\%$, $\ldots$, $y_n\\%$ of the total batch payout. -2. Then, the remaining amount will be distributed among `fee=false` recipients $X_1, X_2, \ldots, X_m$ in the ratio $x_1 : x_2 : \ldots : x_m$. +1. Firstly, `fee=true` recipients $X_1, X_2, \ldots, X_n$ will receive $x_1\\%$, $x_2\\%$, $\ldots$, $x_n\\%$ of the total batch payout. +2. Then, the remaining amount will be distributed among `fee=false` recipients $Y_1, Y_2, \ldots, Y_m$ in the ratio $y_1 : y_2 : \ldots : y_m$. #### Example 1: no fees, splits add up to 100 From 06a11ae0c172d903d2192100c922520b03cc4a24 Mon Sep 17 00:00:00 2001 From: Dovydas Joksas Date: Sat, 27 Jan 2024 20:20:14 +0000 Subject: [PATCH 13/16] fix subscripts for X and Y --- value/value.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/value/value.md b/value/value.md index ef838f05..17e5ddc1 100644 --- a/value/value.md +++ b/value/value.md @@ -238,8 +238,8 @@ How `Batch payout` is divided between the recipients depends on their `split` an For `fee=true` recipients $X_1, X_2, \ldots, X_m$ with splits $x_1, x_2, \ldots, x_m$ and `fee=false` recipients $Y_1, Y_2, \ldots, Y_n$ with splits $y_1, y_2, \ldots, y_n$: -1. Firstly, `fee=true` recipients $X_1, X_2, \ldots, X_n$ will receive $x_1\\%$, $x_2\\%$, $\ldots$, $x_n\\%$ of the total batch payout. -2. Then, the remaining amount will be distributed among `fee=false` recipients $Y_1, Y_2, \ldots, Y_m$ in the ratio $y_1 : y_2 : \ldots : y_m$. +1. Firstly, `fee=true` recipients $X_1, X_2, \ldots, X_m$ will receive $x_1\\%$, $x_2\\%$, $\ldots$, $x_m\\%$ of the total batch payout. +2. Then, the remaining amount will be distributed among `fee=false` recipients $Y_1, Y_2, \ldots, Y_n$ in the ratio $y_1 : y_2 : \ldots : y_n$. #### Example 1: no fees, splits add up to 100 From 83322573c7e0d4bb8946d935357e0b37c867ae52 Mon Sep 17 00:00:00 2001 From: Dovydas Joksas Date: Sat, 27 Jan 2024 23:15:09 +0000 Subject: [PATCH 14/16] clarify how multiple fees are deducted Co-authored-by: Keunes <11229646+keunes@users.noreply.github.com> --- value/value.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/value/value.md b/value/value.md index 17e5ddc1..3324e029 100644 --- a/value/value.md +++ b/value/value.md @@ -378,7 +378,7 @@ Batch payout: **1000 sats** In this case, there are two `fee=true` recipients, so the calculation will have to be done in two steps: 1. `C` will receive $16\\%$ and `D` will receive $4\\%$ off the top of each payment. -2. The rest of the payment (i.e., $100\\% - 16\\% - 4\\% = 80\\%$) will be distributed among `A` and `B` in the ratio $101 : 99$. +2. The rest of the payment (i.e., $100\\% - (16\\% + 4\\%) = 80\\%$) will be distributed among `A` and `B` in the ratio $101 : 99$. Suppose that the listener chose to send a 2500-sat boost, which the app decides to distribute immediately among the recipients: From 405b4cebfe52fa3f9da9af21df4be94461bae289 Mon Sep 17 00:00:00 2001 From: Dovydas Joksas Date: Mon, 29 Jan 2024 13:57:20 +0000 Subject: [PATCH 15/16] clarify `Listener payment` --- value/value.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/value/value.md b/value/value.md index 3324e029..b810cf16 100644 --- a/value/value.md +++ b/value/value.md @@ -231,8 +231,8 @@ When all combined, together the recipients will receive ``` `Listener payment` and `Interval count` refer to one of the following scenarios: -- either the amount of a one-time payment made by the listener (with `Interval count` usually being 1) -- or the amount being streamed per-minute by the listener (with `Interval count` referring to the interval in minutes at which payments are sent by their client) +- `Listener payment` is either the amount of a one-time payment made by the listener (with `Interval count` usually being 1) +- or `Listener payment` is the amount being streamed per-minute by the listener (with `Interval count` referring to the interval in minutes at which payments are sent by their client) How `Batch payout` is divided between the recipients depends on their `split` and `fee` values. From 1dd94b944bc596aebb509009010c1b5972faa52f Mon Sep 17 00:00:00 2001 From: Dovydas Joksas Date: Mon, 29 Jan 2024 13:58:06 +0000 Subject: [PATCH 16/16] clarify subtraction --- value/value.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/value/value.md b/value/value.md index b810cf16..51e3ecf9 100644 --- a/value/value.md +++ b/value/value.md @@ -387,7 +387,7 @@ Batch payout: **2500 sats** 1. `fee=true` recipients are paid first: - Recipient `C` gets a payment of 400 sats (calculated using $2500 \cdot 0.16 = 400$) - Recipient `D` gets a payment of 100 sats (calculated using $2500 \cdot 0.04 = 100$) -2. After that, `fee=false` recipients get the remaining amount of 2000 sats (calculated using $2500 - 400 - 100 = 2000$): +2. After that, `fee=false` recipients get the remaining amount of 2000 sats (calculated using $2500 - (400 + 100) = 2000$): - Recipient `A` gets a payment of 1010 sats (calculated using $2000 \cdot \dfrac{101}{101 + 99} = 1010$) - Recipient `B` gets a payment of 990 sats (calculated using $2000 \cdot \dfrac{99}{101 + 99} = 990$)