docs: add initial f02 design proposal

[rvagg]

This doc is a design proposal for the Solstice f02 implementation, how it works, and why. It assumes the FIP-0118 text; SWA, SRA, orchestrator, and the w0/w1/w2 weight names are as defined there. In this design f02 becomes the stream engine: each block it evaluates the weight records, pays the miner, accrues the service stream's portion, and burns the exact residual; SWA governance writes queue inside f02 under the timelock and apply when due. Headlines: settlement is pull, not push, replacing the FIP's per-epoch payouts with a permissionless Claim, where funds go to the wallets the share map names; storage position 9 keeps the grand minted total, counted at accrual, so FilMined and every client's circulating-supply logic is untouched and the per-stream decomposition is derived; f02 is quarter-agnostic (periods, gates, and cadence are contract-side concerns); per-block-hot values stay inline as bare integers and everything else is offboarded.

Coming out of this, if we agree on this approach, the next steps would be to integrate it into the FIP as one or more PRs:

1. A technical summary of this design as the FIP's normative f02 section, as one unit: state layout, the eight methods, the pending-write queue and its timelock semantics, stream ids, tombstones and removal, the weight-record encoding and fixed point. Most of the above isn't specified in the FIP at all.
2. Accrue-and-claim replaces "pays each orchestrator directly each epoch"; add Claim; delete the failed-send-burns rule.
3. Flip 2.5: position 9 keeps the grand total, FilMined unchanged, decomposition derived, accrual-time minting stated.
4. State the residual rounding rule (burn = BR - miner - service) as authoritative; drop "per-block and per-epoch division are identical" (false under integer rounding).
5. Schedule validation moves into f02 at queue time against the projected schedule, and the last-valid-vector fallback is deleted; SetShares binds immediately, so the quarterly cadence becomes normative SRA discipline rather than an f02 property.
6. SWA-side consequences: the SWA keeps its own gate step counter (deriving position from f02's stored w2 breaks during a hold, and off-grid); cancellation rules restated in terms of the queue's mechanism/discretionary origin.
7. Value MAX_STREAMS and MAX_RECIPIENTS (currently named, never valued) low, with the assertion that raising them takes a future FIP + network upgrade that also reshapes storage for the new scale.

[wjmelements]

this design sgtm

[wjmelements]

if recipient does not yet have an ID, create placeholder account

[rvagg]

what's the case for allowing nonexistent actors to be recipients once we get to this point? it seems like that might be a failure mode and silently letting it sail through might not catch someone's fat fingers. I think I'd rather reject if no actor rather than letting it sail through

[rvagg]

Pushed updates in latest commit:

• total_service_minted added; T/B/S stored, M = T-B-S derived; claimed_total dropped
• tombstones carry payable only, delete when drained; no cap needed
• queue: (id, op) slots, occupied slot rejects; revise = cancel + requeue, hold restarts
• StepWeightRecords: gate write as its own method, the one uncancellable op; origin field gone
• SetShares rejects unresolvable recipients (SRA pre-validates at registration)
• propose MAX_STREAMS=8, MAX_RECIPIENTS=64 (~21-31 KB worst case)
• sizes measured with bigint_ser amounts (original was just u64, ooops)

Want to take a look @wjmelements? I might get a FIP update PR going so others can see the implications.

[rvagg]

integrated to FIP in filecoin-project/FIPs#1272

[rvagg]

New commit added here 1d4b1d3 with some details that came up during implementation - the two values in state now that we can delete cause they're constant are a little weird, well, "simple" is fixed at 330M FIL but "baseline" got fixed at 768335872210768889362796814 attoFIL during the process that fixed it there.

It's static now in practice so we can const these but calibnet is slightly off that number: 769999999891760986050180387. So this change, by making it a cost, will shift calibnet's reward calculation slightly. All it should mean is that reward per epoch goes down, by -0.0000321%, and since it's calibnet, nobody really cares at that scale I think.