Improve the description of splits and fees

[joksas]

These clarifications are based on the discussion #434 (comment)

It is clarified that the meaning of split differs depending on whether fee is false or true.

Three examples are provided:

1. No fee recipients, splits add up to 100. Additionally, it is demonstrated how to batch payments.
2. No fee recipients, splits don't add up to 100.
3. Both fee and non-fee recipients are present.

The new version includes some LaTeX for mathematical expressions (e.g., $\dfrac{50}{50 + 40 + 10}$). GitHub (web version) can successfully render these, but https://podcastindex.org/namespace/1.0 may need to be updated with MathJax or KaTeX. If that's a problem, I can remove LaTeX.

[ericpp]

Can payment amount, interval payout, and interval count be defined here? I assume payment amount is the recipient's percentage of the total payment and interval payout * count is the total payment.

[joksas]

Good catch! That part should be adjusted.

[joksas]

What do you think?

8728460

[ericpp]

Is it worth making a distinction between intervaled and non-intervaled payments? Is the per-recipient calculation different for them?

[joksas]

The calculation is not different, it's just that Interval count may not make sense for boosts, so I thought it needs to be at least acknowledged.

I'm not really sure about that part. Open to suggestions on how to better word it. Or if it's necessary at all.

[ericpp]

Here's my understanding of the payment calculation. Hopefully I have it right:

Recipients are divided into fee recipients (fee=true) and share recipients (fee=false):

• Fee recipients are paid first using split as their direct percentage of the total payment.
• Share recipients are paid next using split as their share of the remaining payment (after fee recipients are paid).
  • All share recipient split values are summed together.
  • Each share recipient receives a percentage of the remaining payment obtained through dividing their split by the sum of all share recipient splits.

[joksas]

Here's my understanding of the payment calculation. Hopefully I have it right:

Recipients are divided into fee recipients (fee=true) and share recipients (fee=false):

• Fee recipients are paid first using split as their direct percentage of the total payment.

• Share recipients are paid next using split as their share of the remaining payment (after fee recipients are paid).

  • All share recipient split values are summed together.
  • Each share recipient receives a percentage of the remaining payment obtained through dividing their split by the sum of all share recipient splits.

That's exactly right!

[algrid]

My interpretation was that the split value coming with fee=true means a share calculated out of the total splits sum, just like for other non-fee items. But I guess that's wrong and everyone interprets it as a % value.

[algrid]

I find it a bit confusing that the split attribute value uses different units depending on the fee attribute value. But that's not a big deal, we just need a bit better spec description and some examples to make it clear to everyone.

[keunes]

Thanks! Quite clear overall I'd say. Just a minor comment.

[joksas]

Thanks! Quite clear overall I'd say. Just a minor comment.

Thank you! Merged!

[MerryOscar]

I find it a bit confusing that the split attribute value uses different units depending on the fee attribute value. But that's not a big deal, we just need a bit better spec description and some examples to make it clear to everyone.

@joksas I also find this very confusing.

Having the split attribute behave differently based on the fee attribute adds complexity to an already complex setup - trying to work this out in your head is basically impossible and in my opinion will lead to a massive amount of support queries.

What is the problem we are trying to solve here?

I read through the discussion in #434 (comment) and it seems that @keunes outlined the splits logic like this:

Boost = 300 sats

App takes fee of 1% (= 3 sats)

Whatever is left (300-3=297), is split according to the value block:

Host split is 3 (= 75% of total splits) --> 0,75*297 = 222,75 (rounded down to 222 sats)
Co-host split is 1 (= 25% of total splits) --> 0,25*297 = 74,25 (rounded down to 74 sats)

However this is not how Fountain works - we take our fee on top of the boost - so our logic would look like:

Boost = 300 sats
Fountain Fee 1% = 3 sats
Cost to User = 303 sats

Original boost amount split according to the value block:

Host split is 3 (= 75% of total splits) --> 0.75*300 = 225
Co-host split is 1 (= 25% of total splits) --> 0.25*300 = 75

(we would also round down in the case of decimals)

---

I would strongly suggest that we think carefully around adding this layer of complexity to the spec and I'm still not sure why this change is necessary?

Surely the simplest way to reason with splits is that you 'split' the payment based on the ratio of the values? Simple to understand and no complex 'if this then that' logic.

Based on all of the above - if we are going to change the language in the spec I would suggest we remove any mention of treating fee splits differently.

[francosolerio]

The reason we formulated the split mechanics as it is today is the interaction between fees and value time split.

Say I use some service to host my show, or have additional functionality like op3 and want to send a 10% split (fee) their way. Then I insert some songs as value time split into my show. While these songs play, my own split is reduced in favor of the split for the owner of the remote item. This works as intended. But if we don't treat fees as special and don't calculate them before all other splits, the op3 split is reduced too. For a show consisting mainly of remote items, that would mean the value sent to services is reduced a lot. I'm not sure this is a side effect the producer expects when using both fees splits for services and remote items for content. Keep in mind that some services can have in their license a fixed percentage split they ask to be sent their way in exchange for the service.

My personal idea as a producer is that the percentage I want to send to some service via a fee split stays the same if I use remote items or not. But we can discuss on this if you have different ideas or find a way to obtain the same result in a easier and more intuitive way.

[MerryOscar]

@francosolerio aah ok thanks for the detailed explanation that makes sense as a rational for doing this - however I still think the complexity it introduces is not worth it.

Fountain for example takes a fee split for the podcasters we onboard - and I personally would rather have our fee reduced during value time splits than over-complicate the spec and confuse everyone.

---

Either way - we agree the use case is this:

"As a producer I want the percentage I send to some service via a fee split to stay the same if I use remote items or not."

My questions to everyone would be:

• is this use case worth supporting given the additional complexity?
• which services that take a fee are calling for this?

[thebells1111]

@MerryOscar I agree the split shouldn't be a percentage, but should have the percentage derived from the split total.
However, what we need a consensus on is how to calculate the split total, because some may add all splits including fee=true and others may use just the fee=false splits. I'm in favor of simply adding all of the splits including 'fee=true' to come up with the total split, but that's not a hill I'm willing to die on.

My reason for adding all of the splits is it prevents this scenario. Imagine the 'fee=false' are a: 50 and b: 50. So, the split total so far is 100. Now, imagine someone puts in their podcast a 'fee=true' and the split is 200. How is that handled for a 1000 sat boost? By adding all of the splits, including fee=true, this becomes less problematic.

A hill I am willing to die on is I won't ever add fees to the boost. When I boost 1000 sats, I expect 1000 sats to be taken out of my wallet, and would be bothered if I saw 1200 sats removed because the podcaster had a bunch of services adding up to 20%. That 20% should come out of the podcasters pocket not mine. And in the case above, where fees add up to 200%, the podcaster would end up sending 3000 sats even though they only intended to send 1000 sats.

The only caveat to that would be if the app decides to take a cut. I could see an argument for adding the app's cut to the top of the boost, almost like a tax, since the podcaster didn't decide which app the listener would use, and one app could decide to take a 20% cut if they wanted to. In that case, the app shouldn't get 20% of what was intended for the podcaster, because the podcaster didn't have a say in that. However, with the splits, the podcaster has complete control of the split amounts, and should be responsible for paying them out of the listeners initial boost amount.

[thebells1111]

@francosolerio I also agree that the fee should be the complete percentage as intended by the remoteItem, so if they intended for a service to get 1%, then that service should get 1%. However, the fee being a split instead of a percentage isn't an issue. Since I have to fetch the remoteItem and get it's valueBlock anyway, I just run it through my splitToPercent function to determine what the percent I send to the service would be. I actually want the fee to be a split instead of percentage, because with it being an int there's no way to enter fractional percentages for a service.

One issue I've run into using remoteItem is how to handle when the podcast value block and the remoteItem valueBlock have the same service in their splits as a fee. For example, they may both have OP3 with a 1% and 3% split effectively. So, should OP3 get 4%? I've had cases were a fee ends up combining to be 10%. What I've been doing is taking the larger of the percentages and using that instead of adding them all together.

[MerryOscar]

A hill I am willing to die on is I won't ever add fees to the boost.

@thebells1111 just to be clear - we only add our fountain app fee on top of the boost - not any of the fees in the value block:

example boost for 100 sats:

value block:
- main podcaster split - 95%
- podcaster op3 service split (fee=true)  - 4%
- podcast index split (fee=true) - 1%

fountain app fee - 1%

user sends the following:
- 95 sats to the podcaster split
- 4 sats to op3 service fee
- 1 sat to podcast index fee

- 1 sat for fountain app fee added on top

• podcaster service fees come out of the podcasters share
• app fees get paid by the listener on top of the boost value so that the podcaster still gets the full amount

[MerryOscar]

One issue I've run into using remoteItem is how to handle when the podcast value block and the remoteItem valueBlock have the same service in their splits as a fee. For example, they may both have OP3 with a 1% and 3% split effectively. So, should OP3 get 4%? I've had cases were a fee ends up combining to be 10%. What I've been doing is taking the larger of the percentages and using that instead of adding them all together.

this is another great example of the complexity of the if this then that logic being proposed here - the edge cases will pile up and it will be impossible to reason what's going on without a calculator or spreadsheet.

we should just add up all the splits and calculate the percentages - simple

[thebells1111]

we should just add up all the splits and calculate the percentages - simple

I'm not necessarily opposed to this, even for fees. My only concern is fees are typically used by podcasters to ensure a TLV record is sent to a service that provides them valuable stats, and I don't want to see a fee percentage knocked so low that the TLV record isn't being sent and the podcaster loses out on those stats they want.

[MerryOscar]

If podcasters want to maintain a certain split at 1% - why can't hosting companies just build this into their splits editing ui instead of pushing this it onto the spec so everyone else has to run complex calculations that inevitably will produce different results in different apps, and require listeners to get out a calculator or spreadsheet to validate?

[daveajones]

I think I agree with basically removing the concept of a "fee" split. In the early days of working out the spec, much of this was envisioning how things would work in the future because there was literally only one client that supported the value tag (Sphinx) and they needed a fee. Then we decided to do the PI API "fee", and it made sense to have that attribute.

But, now that we are using the splits as a way to activate third party features, the biggest issue is we can't ever do a sub-1% split, which could become a big problem at much higher totals. If we just remove the "fee" attribute altogether then people can more easily sub-divide what they are wanting to send where. You can still do a 1%. But, you can also do a .5% or something else.

Will discuss in the board meeting.

[francosolerio]

@daveajones @MerryOscar I would like to hear from Cameron from IPFSPodcasting, @johnspurlock from OP3 and others who provide services relative to P2.0, as removing the fee calculation protection from VTS reduction might create unfavorable conditions for the developement of such services.

[johnspurlock]

I like the idea of removing the fee concept - a split is a split. If folks want to to use services and want these services to exist in the future, they should give them a proper split (participate in both large and small txns) and not try to come up with ways to give them as little as possible. That's not a proper partnership.

[ericpp]

I think standardizing on one calculation rather than this split percentage/share calculation makes it easier to understand and implement for everyone.

It may still be useful to have the 'fee' flag in there purely as a flag to denote fees vs non-fees. Some apps show them differently and it's nice to see how much of my sats are going to the podcasters vs the services/infrastructure.

[thebells1111]

I'm actually okay with removing fees as well. My only concern (and this isn't about fees), is if a podcaster has a service at a 1% split, and the remotePercentage is set to 90% with that podcast as a remoteItem, it will lower that service to .9%. That means there's a higher threshold before a TLV record is sent to that service. Maybe it's not a problem worth worrying about and I'm overthinking it, but I'd like some way for the podcasters to be able to say "Hey, this service getting a TLV record is really important to me, because I need the data".

[thebells1111]

Another thing we'll have to keep in mind is how to grandfather old valueblocks that were made with fee. I suspect one of the easiest ways is to just ignore the fee, and count that recipient as normal split.

[francosolerio]

@thebells1111 If I host my show on IPFS podcasting and decide to send 1% of my income to them (they might actually make it mandatory by license), if 90% of my content is songs with VTS 90% split, the app is actually sending ~0.1%, one tenth of what I what I expected to send. Should the producer calculate and adjust the IPFS split at the end of each show, calculating the effect of each remote item to compensate it and get back to the 1% required?

This will make things easier for apps developers (hey, that's me!), but much more obscure and unpredictable for show producers.

[ericpp]

This should probably be in a dedicated discussion thread rather than @joksas 's excellent PR.

[Cameron-IPFSPodcasting]

TLDR; (My $0.02) Keep fee=true, but don't change a share to a percentage based on "fee-true".

I've always thought the word "percentage" was a typo in the original docs. That all the split numbers were a "share". This says ...this split should be calculated as a fee, meaning its percentage (as calculated from the shares) should be taken off the top... IMO, that means even the fee is converted to a percentage based on the share value. A podcaster could then define 0.5% by making the shares add up to 200 (and setting fee=true split="1").

With remote items, fee=true was meant to pay those first before sending (90%) to the remote item. Sending 90% to the remote item comes from all the non-fee channel/item level splits. This way, a 1% split to a fee=true (op3/sf/ipfs) wouldn't be reduced 90% (to 0.1%).

If there were a fee=true recipient at the channel level, and nothing for that recipient at the item level, they would still get their fee, and be excluded from the remote item split. OTOH, if they were fee=true at the channel level, but also specified at the item level without fee=true, it's an override without a fee (so they lose 90% to the remote item with all the other non-fee entries).

Item level splits override channel level splits. So you don't add them together. Instead use the item level value. This allows the podcaster to override the default (channel) split for a specific item/episode. Explained in the last paragraph here.

[algrid]

As a developer I'm ok with getting rid of the "fee" concept, that would indeed simplify the calculations.
On the other hand, we can go in another direction and replace splits with percentages completely. The only responsibility for podcaster would be to ensure that the total is 100%. In a way that may look more "traditional" for producers and other non-technical people.

[francosolerio]

I would strongly advise against moving to percentages and making it mandatory to ensure the total is 100. It would make errors unmanageable by the apps and lead to a bad user experience.

What should an app do if the splits don't add up to 100?

• Don't send boosts and streams: the user will think the app is bugged and complain with the developer (maybe with a bad review on an app store)
• Display a panel signaling the error to the user: the user has no way to correct this and would be annoyed (and maybe again complain and write bad reviews).

Mistakes happen, podcasters are human, and all this is new. Podcast hosting provider might provide methods to enforce correctness of the total split sum == 100, but many podcasters code their feed by hand.

Considering the split values as shares makes the system much more resistent to all this.

In the spec we can suggest to choose shares that add up to 100 to make all the reasoning more intuitive, and the hosting providers can do the same, without making it mandatory.

[algrid]

Having a simple requirement for percentages to add up to 100 in a way makes human mistakes obvious. Easy to detect. When similar mistakes happen with splits there's no way to detect that. Btw, for splits it would be possible to introduce a (redundant) "splitSum" attribute to make similar check possible.
There are basically two ways to handle an incorrect percentage configuration in the app: 1) show an error message and prevent any payments for such broken configs or 2) try do "fix" the percentages doing a similar to splits calculation (and probably displaying a warning to the user). If 1) is too annoying for users, then 2) should work.

Anyway, I'm absolutely ok with splits. The only thing I would like to avoid is mixing both splits and percentages. This makes the calculations messy and, as we can see now, easy to misinterpret.

[ericpp]

Shares and percentages are functionally equivalent if all shares total to 100, which makes 1 share equal to 1%. People who want to use percentages can enter them in as shares so long as all of their shares total to 100.

Shares have the added benefit of always operating on the total amount rather than on an assumed total of 100%. There's never a case where a portion of the total amount is undefined.

For instance, how would you express a 1/3 split between three people?

• Percentage model: 33%/33%/33% = 99% leaving 1% undefined.
• Share model: 1:1:1 = 1/3 + 1/3+ 1/3 = 3/3 = 100%

[joksas]

OK, had a few weeks of me time to emotionally recover from this thread, and I'm ready to rejoin.

---

Met with @MerryOscar this week, and I now believe that the following approach will cover all use cases, while being sufficiently simple:

All splits act like shares. They don't have to add up to 100.

Calculations on the player side

For recipients with splits $x_1, x_2, \ldots, x_n$, the sat amount will be distributed in the ratio $x_1 : x_2 : \ldots : x_n$.

For example, if recipients A, B, and C, have splits $5$, $4$, and $1$, respectively, then the payment should be divided in the ratio $5:4:1$:

• A will receive $\dfrac{5}{5 + 4 + 1} = 0.5 = 50\%$ of the payment
• B will receive $\dfrac{4}{5 + 4 + 1} = 0.4 = 40\%$ of the payment
• C will receive $\dfrac{1}{5 + 4 + 1} = 0.1 = 10\%$ of the payment

Player fees

Players are responsible for forwarding listeners payments. Thus players can decide themselves what fraction (or flat amount) they charge and how—this behavior doesn't have to be described in the spec, because players will not be recipients in the feed.

Example 1

Recipients A, B, and C in the feed have splits $5$, $4$, and $1$.

App P charges 1% of the payment as a fee.

Listener sends $1000$ sats.

• P charges 1%, i.e., $10$ sats.
• P uses the spec to distribute the remaining $990$ sats in the ratio $5:4:1$:
  • A receives $50\%$ of $990$ sats, i.e., $495$ sats
  • B receives $40\%$ of $990$ sats, i.e., $396$ sats
  • C receives $10\%$ of $990$ sats, i.e., $99$ sats

Example 2

Recipients A, B, and C in the feed have splits $5$, $4$, and $1$.

App Q charges 1% of the payment on top.

Listener wants to send a $1000$-sat boost. The app charges $10$ sats on top, i.e., the listener pays $1010$ sats.

• Q gets $10$ sats.
• Q uses the spec to distribute $1000$ sats in the ratio $5:4:1$:
  • A receives $50\%$ of $1000$ sats, i.e., $500$ sats
  • B receives $40\%$ of $1000$ sats, i.e., $400$ sats
  • C receives $10\%$ of $1000$ sats, i.e., $100$ sats

Other uses of fees

If all the recipients live in a feed, the current concept of fees (i.e., take $x\%$ off the top) can be simulated using simple (share-based) splits.

The only legit use case I can think of right now is the Podcast Index, which too may simulate this behavior using simple splits.

Podcast Index use case

When players fetch value recipients via the Podcast Index, the Index currently inserts itself as a 1% fee recipient.

If the players start ignoring the concept of fees, the Index would receive too much or too little of the payment. For example, if the recipients were A and B with splits $1$ and $1$ (i.e., intending to split the payment $50:50$), and the Index was inserted as a recipient with a split of $1$, the payments would be distributed in the ratio $1:1:1$:

• A would receive $\dfrac{1}{1 + 1 + 1} \approx 33.3\%$ of the payment
• B would receive $\dfrac{1}{1 + 1 + 1} \approx 33.3\%$ of the payment
• The Index would receive $\dfrac{1}{1 + 1 + 1} \approx 33.3\%$ of the payment

Because this is a very niche use case, I'm proposing that if the Index wants to insert itself for 1%, it can do so by transforming the splits so that it is indeed paid 1%, while the ratios in the original splits are preserved.

In this specific case, the Index would transform the splits to $99$, $99$, and $2$, and the payment would be distributed in the ratio $99:99:2$:

• A would receive $\dfrac{99}{99 + 99 + 2} = 49.5\%$ of the payment
• B would receive $\dfrac{99}{99 + 99 + 2} = 49.5\%$ of the payment
• The Index would receive $\dfrac{2}{99 + 99 + 2} = 1\%$ of the payment

This ensures that the Index gets 1% of the payment, while A and B still split the remaining amount $50:50$.

Importantly, this transformation would only have to be done by the Index. The complexity is hidden from the players. They just use the usual share-based calculation. The philosophy is that if someone wants a more complex use case, they handle the complexity themselves. For Podcast Index specifically, I'd be happy to help @daveajones to implement this transformation.

The only disadvantage to this is that if the players expose the splits to the listeners (which I don't think they should do, they should use the percentage abstraction), the creator might be surprised to see different splits than what they set in the feed, even if the end result achieved is the same.

Why not require to add up to 100?

1. With the current spec, where splits are integers, this would prevent non-integer-percent recipients. We may allow floating-point splits, but that's usually avoided in financial calculations due to precision issues.
2. It's a UI nightmare:

• If splits don't add to 100, players may block the payment
• If splits don't add to 100, players may normalize the splits, which is exactly what the current spec does, so why require things to add to 100?
• On the hosting side, if a user unchecks a box which says "give 5% to service X", we have to require the user to readjust the splits for every episode which has custom splits.

Some services need at least 1 sat to work?

Some services provide things like analytics by receiving a fraction of each payment. Should there be a way to signal to the players that they should receive at least something?

For simplicity, I think we should avoid it at this stage, and leave it to the players to decide how to do the rounding. Some players already ensure that each recipient gets at least 1 sat, which I personally believe is very reasonable.

[nathangathright]

Great job @joksas! This feels clear and straightforward.

[francosolerio]

No mention of Value Time Split. @joksas do you think that fees to services should be diminished during VTS segments?

[Cameron-IPFSPodcasting]

Much better. I think Example 2 showing app fees "on top" are what is used today. Any app fees are paid by the user (10 sats), and the podcast always gets what is specified (1000 sats). Agreed that app fees have nothing to do with the RSS allocation.

The reason for fee=true inside the RSS, is for calculating value time splits ("90% goes to the musicians"). Setting "fee=true" means that share comes "off the top" before sending (90%) to the VTS.

Here's an example where 100% goes to the Musician. The shares add up to 111.

For a 1000 sat boost...

Without VTS, fee=true doesn't mean anything, and everyone gets their share/percentage (90.09% + 9.01% + 0.90% = 100 % above)

But when VTS is active, the musician gets 100% of the non-fee splits (90.09% + 9.01% = 99.10%). So...

Because PI has fee=true, they get their share (1/111 = 0.9%) before "100%" goes to the musician.

If PI didn't have fee=true, the musician would get 100% and the other splits would get nothing. Take a look at the example link to test what happens (you can change variables and it will recalculate).

[joksas]

No mention of Value Time Split. @joksas do you think that fees to services should be diminished during VTS segments?

I very much agree with @Cameron-IPFSPodcasting's use case, but I honestly think that for now, we should prioritize the simplicity of implementation for the players. At the moment, it's chaos and I would rather have something simple than something with more features but inconsistent across the ecosystem. That would mean that yes, for now, I don't think we should have the concept of fees.

In the future, when the ecosystem is more mature, and we see more services and use cases, I can see the spec being adjusted for more advanced use cases.

Currently, to ensure that services like OP3 receive at least one sat (for listen-time stats), I think we can encourage (but not require) players to send each recipient at least 1 sat (even if the exact amount is less than 1). Fountain already does that.

For services that may have minimum required percentages, for now the creators might simply need to give them a larger split to ensure that they get the required percentage even when the VTS is on.