Superfluid Tech Deep Dives - Maths of Generalized Distribution Agreements

For the purpose of this article, the index is limited to being proportional distribution index. In this form, each subscriber subscribes to a number of units of the index. And number of units determines the proportional amounts subscribers should receive from the distributions. You can think of dividend payments from Microsoft to its share holders is such example, where the number of shares at ex-div date determines your dividend payout amount at the payout date.

The name of the semantic function for subscribers is updateSubscription.

The function of which how the publisher distributes money is the distribution curve.

Distribution curve can be any arbitrary continuous function, but for a practical solvency response system (in this case, a system that can check if the publisher still have positive balance left), it is desirable to have a distribution curve that is monotonically non-decreasing.

However, instant distribution is a special case even though it is not a continuous function. It can still work because it doesn't have a curve at all hence some specialization in implementation could be done to accommodate that fact. The name of the semantic function for the publisher of a instant distribution index is distributeValue.

For the purpose of this article, we will also explore the constant flow distribution curve, where publisher distribute one big flow at a constant flow rate to all its subscribers, where subscribers proportionally gets smaller flows according to their number of units. The name of the semantic function for the publisher of a constant flow distribution index is updateConstantFlowDistributionRate.

On a note of space complexity, for a publisher, the cost of storing its indexes is constant O(1). But for the subscribers, it is rather of linear O(N), for reasons this article will not elaborate more on.

Since to calculate current balance of a subscriber, it is necessary to iterate through all its subscriptions, the time complexity story is the same for subscribers.

Common variables

• t_s: settled at
• sv: settled value

Variables for publisher

• vpu: value per unit (of the index).

Variable For subscriber

• svpu: settled value per unit (of each subscriber).

How these variables are updated:

1. Publisher vpu is always updated for either a publisher operation (distributeFlow, or updateConstantFlowDistribution) or a subscriber operation (updateSubscription units).
2. Publisher's balance curve is indistinguishable between sending to 1 participant to N subscribers. This observation also leads to the design of using "lens abstraction"² when defining the specification.
3. A subscriber's svpu is updated only when a subscriber operation applied to it.

Per principle (2), balance function for publisher is the same as a simple 1 to 1 instant transfer, which is simply a constant function of a fixed value settled per principle (1).

Balance function for subscriber is:

sv + floor (u * fromIntegral (vpu - svpu))

Here is an illustrate an example case per principle (1):

First of all, the constant flow formula are provided through the lens abstraction, it is just a fancy way of saying some of the values of the formula are provided are a set of functions themselves:

-- ... (omitted noisy details)
    settledAt          :: Lens' amuLs (SFT_TS sft)
    settledValue       :: Lens' amuLs (UntappedValue (SFT_MVAL sft))
    netFlowRate        :: Lens' amuLs (SFT_MVAL sft)
-- ... (omitted noisy details)
    balanceProvided (MkMonetaryUnitData a) t =
        let b = sv + coerce (fr * fromIntegral (t - t_s))
        in  -- ... (omitted noisy details)
        -- (.^) is the lens accessor/getter function, similar to "." in OO languages.
        where t_s = a^.settledAt
              sv  = a^.settledValue
              fr  = a^.netFlowRate

What really matters above is the formula in b, and knowing that it needs three set of lenses: settledAt, settledValue and netFlowRate to be able to compute.

Per principle (2), balance function for publisher is the same as the 1 to 1 constant flow, hence its lenses are trivial:

-- ... the data record for publisher
data PublisherData sft = PublisherData
    { pub_settled_at      :: SFT_TS sft
    , pub_settled_value   :: UntappedValue (SFT_MVAL sft)
    , pub_total_flow_rate :: SFT_MVAL sft
    }
-- ... use field template to generated lenses
    settledAt    = $(field 'pub_settled_at)
    settledValue = $(field 'pub_settled_value)
    netFlowRate  = $(field 'pub_total_flow_rate)

Balance function for subscriber is a tad more complex but still succinct. It is also provided through a set of constant flow lenses:

    settledAt     = readOnlyLens
        (\(-- ... syntaticcal pattern matching noise omitted
          ) -> s_t)

    netFlowRate   = readOnlyLens
        (\(( -- ... syntaticcal pattern matching noise omitted
           ) -> if tu /= 0 then floor $ fromIntegral dcfr * u / tu else 0)

    settledValue = readOnlyLens
        (\( -- ... syntaticcal pattern matching noise omitted
          ) -> let compensatedΔ = dcfr * fromIntegral (t_dc - t_sc)
                   compensatedVpuΔ = if tu /= 0 then floor $ fromIntegral compensatedΔ / tu else 0
               in  sv + floor (u * fromIntegral (vpu - svpu - compensatedVpuΔ)))

In addition to the common variables:

• Let fpu be flow per unit, then dcfr is the distribution flow rate of the index: dcfr = fpu * total_units.
• In settledValue function, t_dc is the s_t of the publisher side, while t_sc is the s_t of the subscriber side.

The following visual example should show you how all these formulas compose together nicely.

Here is an illustrate an example case per principle (1):

It should show why compensatedVpuΔ was needed behind the lens abstraction in the "bar sticks algebra" on the bottom right side.