docs(cip): Cardano PubSub CIP — motivation, specification, rationale - #164
Draft
will-break-it wants to merge 160 commits into
Draft
docs(cip): Cardano PubSub CIP — motivation, specification, rationale#164will-break-it wants to merge 160 commits into
will-break-it wants to merge 160 commits into
Conversation
Honest downtime reduces to the silent adversary already specified, so it enters the existing coverage analysis at mu + p(1-mu) rather than sitting outside the threat model. Says so, and narrows the caveat to what is actually open: the shifted-mu prediction is not yet validated against a down-marking simulation, and correlated outages are not captured by one independent p. Three consequences follow: - the bounded-duration argument needs a third qualification, since independence of topology draws is not independence of outcomes when liveness is correlated across epochs; - epoch length is bounded from above as well as below, because unrepaired downtime accumulates over the epoch; - selecting parameters for minimum cost and selecting them for downtime tolerance are different criteria that can disagree at an identical link budget.
… against
Reading the sections composed rather than separately, three things were
wrong.
The adversary model sat under Trade-offs and Limitations, which is not
what it is — it is a definition, and the evidence is measured against it.
It is now a Rationale subsection in its own right, placed before the
Evidence subsection that depends on it. Trade-offs keeps the two fault
classes and what the protocol guarantees instead, which are limitations.
Epoch was used throughout without definition. A Cardano reader will read
it as the ledger epoch and silently convert a per-epoch probability at
five-day intervals; the dissemination epoch is a parameter of this
proposal and need not coincide. Defined once at the top of the Rationale.
Neither the adversarial fraction nor the failure target was ever
justified. Both are assumptions the analysis takes as input, and a
reviewer will ask. Added as open questions, with the note that the target
cannot be argued independently of epoch length.
Also drops a direction word that assumed section order ("enters the
analysis above"), points the residual-failure reference at Evidence
rather than "elsewhere in this Rationale", and records the FORWARD-REF
convention for prose that points at sections not yet written.
Follows CIP-0164's Evidence pattern: define the metrics before showing results, name the designs compared, then the results, then what they do not establish. Placed after the adversary subsection, which is what it measures against. Written from the executed model-family comparison: - what is being measured, including why the criterion is all-or-nothing rather than an average over messages, and how the two instruments differ — a closed-form law derived from an abstract model, and a framework running the reference node logic — so that their agreement is the evidence rather than either alone; - the metric definitions with formulas, including the churn budget and its relation to epoch length; - the five designs, with M1 and M2 noted as the boundary reductions of M5 that give a free consistency check; - the law-versus-measurement agreement over 23 configurations, including the aggregate test that no individual comparison document performs; - the cost comparison at equal safety, and the three conclusions that follow; - a Limits subsection: the measured range and the proposed operating points differ by three orders of magnitude, a small tail correction is unresolved, the state axis is measured less precisely than the cost axis, everything is at one adversarial fraction, and correlated failure is out of scope. Figures are generated rather than drawn. cells.json carries the 23 configurations and five operating points with their configs, seeds and tool commits; make_cip_figures.py builds the SVGs from it and, with --check, fails when a committed figure is stale. Presentation attributes only, since GitHub strips style blocks, and an opaque surface so they read on either theme. Robustness is deliberately left unwritten: those numbers exist only as the laws read at a shifted adversarial fraction, which is a prediction. It says so, and says the cost comparison should not be read as settling the design choice until the churn sweep lands.
Follows CIP-0164's variants radar, with three changes suited to this comparison. Only the surviving candidates are drawn. Five overlapping polygons would be unreadable, and the cost comparison already rules out three of the five. M2 is kept as a grey dashed reference for the conservative end of the family, which also keeps it out of the categorical palette, where its hue sits too close to M4's to separate once both are filled. The axes are measured quantities rather than qualitative levels, scored best-of-three per axis so the outer ring is the best value, with the raw numbers printed beside each axis. The churn axis is predicted from the coverage laws rather than measured, and is marked in the figure, in the caption and in the prose. It goes under Trade-offs rather than Evidence deliberately: Evidence reports measurements on individually meaningful axes, whereas this places four incommensurable axes on one frame, which is a summary judgement. The prose states that enclosed area carries no meaning and only per-axis position should be compared. The shapes carry the point the parameter-selection open question makes in words: M3 is a spike and M4 is even, because a mechanism that is cheap by being small is also the one with least margin when part of it goes quiet.
Reviewing which designs the figure should carry turned up an error in the cost comparison. It concluded that M1, M2 and M5 are "beaten on every axis at once" — true of the two cost axes it was drawn from, but not of every axis. Recomputing dominance over all four shows only M1 is dominated, by M5. M2, M3, M4 and M5 are each best at exactly one thing: bandwidth, connections, speed, churn tolerance. The claim is narrowed to the cost axes and points at the wider comparison. The figure follows. It now shows all four contenders rather than two, one panel each, with the other three drawn behind in grey. Four filled polygons overlaid in the models' own hues cannot be told apart — magenta against orange falls below the normal-vision separation floor — and the alternative of recolouring would have meant a model changing colour between figures. Faceting keeps every model the colour it has in Figures 1 and 2, which is the point of having model colours at all. Axis names were ambiguous: "Bandwidth" and "Latency" do not say which direction is good, while the scoring makes outward better. They are now Bandwidth economy, Connection economy, Speed and Churn tolerance, all reading the same way, with the orientation stated once above the panels. Also records why these four axes and not others: worst-case connections per node is the natural fifth but is the least reliably measured quantity here, headroom below the target reflects integer parameter steps rather than design, and mean receipt depth would double-count latency.
The trade-off figure was split into four panels because four filled polygons in the models' hues could not be told apart — magenta against orange fell below the normal-vision separation floor. Faceting kept the colours honest but wasted the form: side-by-side comparison is the whole reason to use a radar. Fixed at the source instead. Searching the palette for subsets that clear every colour-vision gate as an all-pairs set turned up blue/violet/green/yellow/magenta, whose worst pair separates at OKLab dE 13.0 — well clear of the target rather than sitting in the warn band the previous mapping needed secondary encoding to excuse. M1, M4 and M5 keep their hue; M2 moves orange to violet and M3 aqua to green. Applied in the generator, so all three figures change together and a model is the same colour wherever it appears. With colours that separate, the figure is one overlay again, and can carry all four non-dominated designs rather than two. That turns out to be the clearest form available: each of M2, M3, M4 and M5 leads exactly one axis, so every axis carries one design's label and the figure names what each is for without a legend. M1 stays out, beaten on all four. Also recolours the frontier line in Figure 2, which was a green that now read as M3's series colour.
Limits of this evidence opened by asserting that the configurations measured are not the configurations proposed. That is the claim a reviewer is most likely to press on, and it was carried by prose alone. Figure 3 now shows it: per design, the failure rates actually observed against the rate of the configuration this proposal uses, with solid marks for counted outcomes and hollow marks for law predictions. Building it corrected the claim. The text said the extrapolation runs "roughly three orders of magnitude"; measured against the data it is 1.8 to 2.1 decades depending on the design, so it now says close to two. The same overstatement appeared in the agreement subsection, which described the measured configurations as spanning three orders of magnitude when the span is 2.46; that reads "two and a half" now. The figure is deliberately not the bandwidth-versus-target curve from the earlier analysis. That would have restated the cost ranking Figure 2 already carries. This one does the job nothing else does — it shows only the distance between what was measured and what is proposed, which is what the surrounding paragraph is about. Figures renumbered so they run in document order: the extrapolation figure is 3, the trade-off radar becomes 4. Also moves the radar's orientation note from above the plot to below it, with spacing.
Captions had grown into paragraphs — the longest ran to about six hundred characters. A table of figures generated from those would be unreadable, and CIP-0164, which maintains one, keeps its captions to a short label and puts the explanation in the body. Every caption is now a name: 28 to 68 characters. The material they were carrying moved into the prose, placed so each figure reads lead-in → figure → takeaway rather than being explained after the fact. Table 4's notes on bold marking and provenance moved out of its caption to the paragraph below it, which also takes them out of the centred block they were wrongly sitting inside. Nothing was dropped, only relocated.
The Robustness subsection was a placeholder saying the numbers were predictions and would not be published as measurements. Experiment E13 has since run: twenty-five configurations across the five designs, honest downtime swept to 12 % of the population, each point scored against its design's coverage law read at the shifted adversarial fraction. Twenty-three of twenty-five place the prediction inside the measurement's interval, and at the largest shift tested all five land on their laws almost exactly. The subsection now states the result, gives the budgets as Table 5, and draws the conclusion the placeholder deferred: the budgets differ by four times, their order is close to the reverse of the cost order, and cost alone therefore does not select a design. It also records the concrete consequence for M3 — at the same budget and the same standing links, (13, 7) reaches 2.17 % against (12, 8)'s 0.54 %. Two things are kept explicit. The budgets are still read off the laws rather than observed, because the budget sits at P(bad) = 1e-4 and cannot be sampled; what the experiment establishes is that the laws apply under churn. And the measurements sit slightly above prediction in the middle of the range, an effect that does not grow with downtime and so does not behave like a mistaken reduction, but is unexplained — in the conservative direction. Also corrects the adversary subsection, which still said the shift had not been checked against a down-marking simulation; relabels the figure's churn axis and cells.json from "predicted" to law-derived-with-validated- reduction; and adds a footnote pointing at the experiment write-up.
Limits recorded that the state axis was measured less precisely than the cost axis, and that links carrying no dissemination traffic were not captured at all — under M3, fourteen of thirty-eight. That was the comparison's weakest axis and also its deciding one, since M3 against M4 turns on held connections. It is measured now, on both instruments, at 200 graphs against the formal side's 25, and every mean lands on the published value. The Limits entry is replaced rather than deleted: what remains true is that the worst-case figures are the largest value in a sample, and an extreme-value statistic grows with the number of graphs and with population size, so they are measured lower bounds on the worst case rather than limits to provision against. Table 4 gains the busiest-node column, because connection limits are sized for the worst node rather than the average one, and the designs separate more sharply there: M3 at 64 against M4's 36, where the means are 38 and 16. The trade-off figure now says three of its four axes are measured directly rather than implying only churn is not.
The latency conclusion said flatly that latency does not discriminate. That is true of the means, which span 0.7 hops, but the depth histograms the instrument already records tell a sharper story at the tail: the deepest wave carries 0.17 % of receipts under M3 against 0.0013 % under M4, two orders of magnitude apart. The claim is now scoped to the mean, with the tail stated and kept in proportion, since it affects a fraction of a percent of subscribers. A footnote points at the write-up. The choice-of-axes note still described worst-case connections as the least reliably measured quantity and the natural fifth axis once it landed. It has landed, and is in Table 4; it is left off the figure only because four axes already carry the argument. Em-dashes reduced from 44 to 1, rewritten as commas, colons, semicolons or separate sentences rather than substituted mechanically, since they were doing several different jobs. The four remaining are in the CIP template's own commented-out section list, not in our prose. Verified separately that every table, figure and caption already sits in a centred block; no change was needed there.
The gap is log10 of the ratio between the measured failure rate and the proposed one. Both are per-epoch probabilities, so the epoch definition cancels and the figure assumes no epoch length. But "2.1 decades" reads as a duration in a document whose central quantity is measured per epoch and which discusses epoch lengths in years, which is a misreading the label invites rather than one a reader should have to rule out. Now stated as a plain factor: 64x rarer, 124x rarer, and so on. Same quantity, no time connotation, and easier to read besides.
Epoch length was an open question with no numbers. Two measurements already bound it, from opposite directions, and putting them together gives the first quantitative handle on it. From below, convergence: topology formation took exactly two dial rounds in every run of every operating point, no variation across 200 runs each, so the floor is a few round-trips. From above, downtime: links are not repaired within an epoch, so setting accumulated downtime equal to a design's churn budget gives the longest epoch it sustains, T = -ln(1 - p_max) / lambda. Three findings. The window is lopsided, seconds against hours, so calling it constrained from both directions is accurate but misleading; only the ceiling binds. The design choice sets rotation frequency, and M3 at (12, 8) sustains about a quarter the epoch of M5 or M3 at (13, 7), which is an operating cost following directly from the parameter split. And aligning with the five-day ledger epoch needs a node population departing less often than once every 2.5 years under M3 (12, 8), against 7.5 months under M5. Figure 3 charts it, with the designs as parallel lines separated only by their churn budgets. Table 6 gives the five-day crossings. The open question keeps what is genuinely open: lambda was not measured, being a property of the deployed population rather than of the protocol. What the analysis fixes is the shape of the trade, so choosing an epoch becomes a question of what reliability can be assumed. Figures renumbered into document order.
The epoch-length subsection presented five days, matching Cardano's ledger epoch, as a bar the protocol should clear. Nothing establishes that. The randomness source is an open question, and its candidates are a block hash or a VRF beacon, neither of which implies a five-day cadence. The framing was also misleading in one direction. The data says short epochs are undemanding and the requirement only becomes severe as the epoch lengthens, so anchoring on five days made the churn ceiling look like a constraint the protocol struggles against rather than one it sits comfortably inside. The design pressure runs toward shorter epochs anyway, since bounded muting is bounded by the epoch length. Table 6 is inverted accordingly: choose an epoch, read the reliability it requires. At an hourly epoch every design needs only that a node stay up for days at a time. What survives is a genuine coupling, now stated as conditional rather than as a goal. The epoch cannot be shorter than the interval at which unbiasable randomness arrives, so the beacon design sets the floor and decides whether the churn ceiling binds at all: under a per-block or dedicated beacon it does not, and under the ledger nonce it does. That turns five days from an arbitrary target into a consequence of a design decision nobody has taken yet. The figure no longer emphasises the five-day line.
Matches the trade-off figure, where the same note reads better after the chart than before it: the reader meets the picture first and the caveats second. Top margin shrinks to suit, bottom grows to take the note with spacing.
The relation is linear in mean time between departures, so on log axes every design is a slope-one line differing only by its vertical offset. That offset is the churn budget: one number per design, already in Table 5 and again, inverted, in Table 6. The figure rendered six numbers as six parallel lines and added nothing to them. Two further reasons to cut it. Its horizontal axis is entirely hypothetical, since the departure rate was never measured, so a reader cannot locate a deployment on it. And clean straight lines on log axes read as a measured relationship rather than as a two-parameter identity plotted over an assumed range. The subsection and both tables stay. A lookup table is honest about being one: choose an epoch, read the reliability it requires. Figures renumbered; four remain, each carrying measurements.
… place Three changes from reading the section as a reader rather than its author. The conclusion never landed. Four consecutive sections each deferred it to the next, and the last deferred it to the reader, so a reviewer could not tell whether the work has a recommendation. A closing subsection now says plainly that two designs remain, that the evidence does not select between them, and what would: whether a node's binding constraint is traffic or connections, which is a fact about operators rather than about the protocol. The open question is rewritten to name that, rather than asking abstractly whether to optimise for cost or for tolerance. M3 at (13, 7) was the most actionable result in the document and appeared as an aside inside a paragraph about something else. It now has a table and a plain statement that any use of M3 should take it. The two subsections describing what and how things were measured are merged, and the metric glossary keeps only the two definitions that are not evident from the table, with the rest folded into a short note. That is about four hundred words returned, from material that was reference rather than argument and did not discriminate between designs.
…er-node cost Epoch length moves out of Evidence to follow "What the protocol guarantees instead". It reasons forward from results rather than reporting them, and it belongs next to the bounded-duration argument, which is the guarantee epoch length actually sets. Limits are ordered by how much they bear on the conclusions, most consequential first, and say so. The extrapolation between measured and proposed configurations now leads; the single adversarial fraction, which changes nothing about the ranking, comes last. Two additions from review. The churn budgets are also a security margin, and the section now says so. Since an offline honest node and a silent adversary are indistinguishable, a budget for downtime is a margin above the assumed adversarial fraction: M3 at (13, 7) still meets the target at mu = 0.217 where M4 breaches it at 0.209. Downtime tolerance and adversary tolerance are one quantity, not two. And a per-node cost model, because both measured costs are per topic and a node subscribing to several pays for each. Both scale linearly so the ratio never moves, but the binding constraint does: bandwidth stays modest even at twenty-five topics, while connections reach 380 against 160 at ten. That is the strongest argument for M4 so far and it is invisible in the single-topic comparison. It carries a qualification that could overturn it, now also an open question: whether links to one peer on different topics share a transport connection is unsettled, and if they do, both designs converge toward the distinct-peer count. Tables renumbered into document order.
The Motivation states five requirements and the Rationale never referred back to them, so a reader could not tell which had been tested and which were structural. The Rationale now opens by taking each in turn: two are met by construction, one rests on the randomness argument and is treated with the guarantees, and the remaining two are the quantitative ones the evidence exists for. Censorship resistance was stated as a requirement on how rare, how brief and how unsteerable suppression is, and each clause now points at where it is answered. The bounded-duration qualifications were a hundred-and-ninety-word paragraph carrying three separate arguments, which is where the section was hardest to read rather than where it was longest. They are three labelled points now. The detectability comparison loses a sentence that restated the bullets above it. The two fault classes are left as they were. That section is already tight and is what the deposit design rests on.
The churn reduction was validated at cells chosen for measurability. It has now also been run at the operating points themselves, under 20 to 30 % downtime, and all nine configurations place the prediction inside the measurement's interval with no detectable bias. The two rounds carry the reduction from an adversarial fraction of 0.20 out to 0.44, and the second tests the configurations this proposal actually names rather than proxies for them. That also bears on the residual. The first round's excess does not reappear at the operating points, which is further evidence it was concentrated noise rather than a defect, though it stays recorded as unexplained. Figure 1 gains the churn cells, hollow against the filled cells at the assumed adversarial fraction. It is a better figure for it: the original 23 hold the fraction fixed and vary each design's own parameters, while these hold parameters fixed and vary the fraction, so the laws are now shown tracking along both directions rather than one.
Both studies carried the coverage laws as roughly 11 % optimistic where failures are rare, on the reasoning that they count a single cut-off node exactly but a small cut-off group only approximately. Neither side's sample could check it: separating a ten-percent effect at those rates needs of the order of 1e5 draws against the published 3e4. One cell was re-run at 170 000 draws on an independent seed. The measured rate is 1.004 times the law. Pooled with both teams' earlier samples, 1 240 failures in 230 000 draws, the factor is 1.009 +/- 0.029 and the 11 % figure is rejected at more than three standard errors. The earlier disagreement resolves as noise in both directions: the formal sample sat at 1.11x and ours at 0.94x, and the truth is on the law. The Limits entry is rewritten rather than removed. What it claimed was that the correction was unresolved in size, which is no longer true; what is true is that it has been measured on one design and the equivalent run for the other is still going. Deleting it outright would have implied both. Figure 1 gains the cell, which is by far the tightest point on it.
The Robustness subsection says any use of M3 here should take (13, 7), and the summary figure then plotted (12, 8). The figure read the published operating points while the re-split sat in the alternatives list. It now prefers an alternative wherever one is marked as such, and carries the measured figures for it: 10.40 copies, 38.0 standing links, 5.51 hops. The shape changes enough to rewrite the prose around it. Under (12, 8) M3 was a spike, innermost on three axes and reaching the outer ring only on bandwidth. Under (13, 7) it leads bandwidth and comes within a hundredth of a point of leading churn tolerance, on the same budget and the same standing links, so the paragraph now describes the re-split doing visible work rather than describing a spike. It also exposes that M5 leads nothing surviving rounding: its churn margin over M3 is 2.18 against 2.17. Recorded as a hint rather than a conclusion, since the full case for dropping it rests on the parameter sweep still to be written up.
…inated Every operating point in Table 4 came from one rule: cheapest configuration meeting the failure target. That rule selects the configuration nearest the cliff by construction, since anything cheaper fails, which is why the comparison has been reading each design at its most brittle point rather than its best. Searching the parameter space against the validated laws and measuring the results shows the cost. M4's step from RF = 8 to RF = 9 buys seven times the churn budget, 1.07 % to 7.43 %, for 1.6 further copies and two further connections. At those parameters M4 beats M5 on every axis, so M5 is dominated outright and M1 with it. Three designs remain, and the radar shows those three. Table 7 becomes M3 (13, 7) against M4 (RF = 9), both measured. On that comparison M4 leads three axes of four; M3 leads bandwidth by 22 %. The section still declines to choose, because no weighting of traffic against connections follows from the analysis, but it now says which way the weight of evidence sits. The radar derives its per-axis leaders from whichever shown design is best, rather than a fixed assignment that went stale as the set changed.
The adversary section excluded an adaptive adversary that re-registers between epochs, but said nothing about one that corrupts already- registered nodes after the epoch's draws are public. That is a different capability rather than a different behaviour: the coverage analysis assumes the adversarial share is fixed before the draw and independent of it, and against a chosen-victim attacker the relevant quantity is the victim's own degree, not the network-wide fraction. Stated as an exclusion only. The cost under that assumption is being analysed separately and is not quoted here, since the premise it rests on is not yet verified.
The bucket count and the serving cap are what make the peer assignment verifiable and bound its abuse, and neither appears in the coverage models, so neither had evidence. Two experiments now supply both sides of the same knob: what narrowing the gate costs in coverage, and what it buys against a flooder. Coverage is untouched while the gate leaves each node twice the survivors it needs, at 279 failures in 32 000 against a law of 0.0088, so verifiability is free where there is headroom. Remove the headroom and it costs five times the law. In the other direction the gate divides an attacker's pressure by the bucket count exactly. The rule falls out of the shape: the largest bucket count still leaving headroom is both coverage-exact and the most dilutive. Two further results carried for the Specification. A deployment that lets the gate alone set degree pays a factor of two, and one extra link buys it back, measured at 2.27 against 2.26 predicted. And the serving cap's failure mode is the opposite of the obvious one: raising the cap gives the attacker more slots on each victim and yet preserves coverage, because the harm is honest dials refused for want of capacity rather than slots lost to the attacker. Figure 5 puts both on one horizontal axis in stacked panels rather than two vertical scales, since a probability and a slot count share no comparison. Carries a FORWARD-REF: the Specification has not yet described either mechanism, so the subsection defines both in passing and records what must exist there.
Three places a reader skimming the section could carry away the opposite of what it says: that the evidence selects a design, that the churn budgets are measured rather than read off the laws, and that the limits are of equal weight. Each is now a GitHub callout rather than another paragraph among paragraphs. Kept to three deliberately. CIP-0164 uses five across a document several times this length, and the value comes from being rare.
Eleven alerts across the Rationale, on a consistent scheme rather than scattered for emphasis: [!NOTE] definitions and couplings the reader must carry forward [!IMPORTANT] load-bearing claims, and claims not to overstate [!WARNING] where the plain reading is the opposite of the evidence [!TIP] a sizing rule an implementer applies directly New: the epoch definition; the two instruments being indistinguishable; M3 (12, 8) not being M3's best showing; efficiency bought with margin; the multiplexing question that could blunt the connection argument; the bucket-count rule; no attribution of silence; bounded duration not being a latency guarantee; the beacon setting the epoch floor. The churn-residual note reverts to prose - it sat directly above the Limits preamble, and three stacked blockquotes read as noise.
The subsection reached for B, r and "survivor headroom" with nothing to attach them to - the Specification that defines them normatively is not written yet, so the figure's axis read as an unlabelled knob. Prose: sketch the mechanism (identity plus epoch randomness selects one of B buckets; peers must fall in it; anyone can recompute the predicate), derive r = (N-1)/(B*RF) from it, and say what r = 10 and r = 1 mean before the figure is shown. Then say how to read the two panels and which direction is good. Figure: define r under the headroom band, mark both panels "lower is better", and label the circled point as the recommendation. Also in the alt text, which had used r without expanding it.
The lower panel plotted K/B at all seven bucket counts as one solid line, next to an upper panel that is entirely measurement. E12 ran four of those seven, so the figure was presenting arithmetic in the same ink as data. Filled markers where E12 measured, hollow where K/B is prediction only, with a key. The prose now carries the strength of the result rather than asserting "exactly": 36 of 48 grid cells within 2 % of K/B, Poisson per-victim shapes, and the exceptions all in the conservative direction where the serving cap truncates the attacker below K/B.
…f, raise the abstract
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The Cardano PubSub CIP, as one document. Replaces the previous stack of #143 (Rationale) and #153 (Specification), whose commits are all contained here; the base is
main, so the diff is the whole proposal rather than one layer of it.docs/cip/README.mdnow carries Abstract, Motivation, Specification, Rationale and Path to Active, with nine generated figures and the script that produces them.Read the rendered CIP — the document as GitHub renders it, with the figures in place. It tracks this branch, so it stays current as commits land. The diff below is the same content unrendered.
Specification
Built from the on-chain state outward, so nothing is used before it is defined: Terminology, Architecture, on-chain state (both registries, the lifecycle, the registration cutoff, the CDDL schemas CIP-0001 requires), identity and keys with the canonical-preimage rules every signature uses, epochs and the beacon as an interface with four stated requirements, topology derivation (registered peers, the verifiable gate, headroom and B, selection, the serving cap), link establishment and the acceptor's normative check order, messages, then dissemination, recovery and retention, then Parameters and Versioning.
Its opening states the standard it aims at, an interoperable implementation written from this document alone, and then each way it does not yet reach it: three components specified as interfaces rather than mechanisms (beacon, address resolution, on-chain validators), the unresolved dissemination design, six of ten parameters carrying a rule rather than a value, and the transport left to the deployment.
The dissemination design is deliberately open. Marked
<!-- OPEN(dissemination-design) -->, it carries both candidates at their best known parameters in Table 3 and says what decides between them, which is a fact about operators rather than evidence (#85). Everything else is stated in terms of "a link kind and its pick count k", so only that subsection changes when the question closes.Rationale
The adversary the proposal is analysed against, what was measured and how, what the guarantees cost, and where they stop. Figures are generated from
cells.jsonbypubsub-node/docs/experiments/make_cip_figures.py;--checkfails if a committed SVG is stale.Two reading conventions the figures hold to: dashing marks a quantity read off a coverage law rather than sampled, and it marks nothing else, so the trade-off radar draws its dominated designs as muted grey shapes and reserves the dash for its churn axis. Enclosed area on the radar has no meaning, and the figure says so.
Conventions
FORWARD-REF(target)marks prose pointing at a section not yet written;OPEN(name)marks a subsection deliberately unresolved, naming what will be fixed there and what decides it. Grep both before calling the proposal complete.