Package revshare is a team revenue realm that IS a subscription provider. The live subscriptions realm supports realm providers but warns, in its own frozen header, that a realm provider "must expose its own crossing path to Claim, or what it earns is stranded." revshare is that crossing path, plus the one thing a team needs on top of it: pulled revenue is split among weighted members into pull-claimable balances.
THE ECONOMIC COMPOSITION, PRECISELY:
Example
1components : subscriptions (live realm — the revenue
2 machine and the upstream custodian),
3 feeledger (member balance accounting,
4 fee cap 0), coinio (payouts, held-balance
5 reads, reserve-protected sweep).
6value boundaries : B1 subscriber EOA -> subscriptions (plan
7 price, origin envelope; governed by
8 subscriptions' own H == U + F). B2
9 subscriptions -> revshare (banker send:
10 ClaimAll pays the caller, and the caller
11 is this realm). B3 revshare -> member EOA
12 (coinio.Payout on Claim/ClaimAll).
13who owns which state : subscriptions owns plans, subs and the
14 provider's claimable balance (revshare's
15 RECEIVABLE); revshare owns the member
16 table, weights, and the member balances in
17 its own ledger. No state is shared; the
18 only coupling is the crossing calls and
19 the coins that move over B2.
20who controls funds : upstream, only a claim by this realm can
21 move its receivable (provider-keyed
22 ledger). Here, member balances move only
23 to their owner (pull claims); the admin
24 can NEVER touch earned balances — sweep
25 reserves them, weight changes affect only
26 FUTURE distributions.
27identity propagation : downstream sees cur.Previous() = THIS
28 realm on every crossing call, so the plan
29 provider and the claim beneficiary are the
30 realm address by construction — no admin
31 or member identity ever reaches the
32 downstream realm.
33conservation : Held == UsersTotal + S (surplus above the
34 Liabilities() reserve, recoverable only by
35 SweepDenom). Distribution is exact: shares
36 are floor(amount*w/W) via the
37 overflow-free split (A/W)*w + ((A%W)*w)/W,
38 and the remainder goes to the
39 highest-weight member (ties: lowest
40 address) — fee_split's deterministic dust
41 policy, so no residual pool exists.
42 Cross-boundary: lifetime Pulled equals the
43 sum of all distributions, and the
44 downstream receivable is NOT part of Held.
45ordering : Pull refuses BEFORE the downstream call
46 (no members configured = refuse), claims
47 downstream, MEASURES the arrival as a
48 held-balance delta, then distributes
49 exactly what arrived. State-after-call:
50 the only local mutations happen after the
51 boundary, on measured coins.
52downstream abort : "nothing to claim" (or any downstream
53 panic) aborts the whole Pull — no local
54 state exists yet to corrupt, by ordering
55 AND by VM atomicity. There is no recover
56 anywhere in this realm, and none may be
57 added.
58replay : a second Pull finds a zero downstream
59 balance and aborts there. Distribution
60 credits are driven by the measured delta,
61 so a replayed Pull cannot double-count
62 even in principle.
63trust : revshare does not trust the downstream
64 reply beyond "it did not abort" — it
65 distributes the measured balance delta,
66 not a reported amount. Downstream
67 validates nothing about this caller; the
68 provider ledger is keyed by address.
69terminal states : plans retire downstream (provider-only,
70 exposed here admin-gated); members can be
71 removed (earned balances survive removal
72 and stay claimable); the realm itself has
73 no terminal state — a team that walks away
74 leaves only pull-claimable balances.
75adversarial callers : Pull is permissionless — it can only move
76 the receivable into member balances at the
77 fixed weights, so a stranger's Pull is a
78 free favor. Plan creation/retirement is
79 admin-gated (the downstream per-provider
80 plan quota is a griefable resource).
81 Members trust the admin for FUTURE weights
82 only, never for earned balances. All
83 entrypoints refuse coin-carrying
84 transactions (the downstream assertNoSend
85 reads the origin envelope; ours matches).
One team per deploy: subscriptions keeps ONE claimable balance per provider address, so a multi-team router behind one realm address could not attribute revenue at the boundary. This is a measured constraint of the downstream API, not a choice.
