Repository navigation
README do-over - #74
yuval-block wants to merge 1 commit into
Conversation
Co-authored-by: Armin Sabouri <me@arminsabouri.com>
b27593f to
f377384
Compare
range-diff for force push b27593fde3 → f3773841ec
|
|
Looks awesome! Clear and correct. If anything, I missed an conceptual high level explanation of where the anonymity comes from. Not the technical details, but something like a mention to standardized denominations or Knapsack density. So that the reader can have an idea of where the anonymity comes from. |
|
ACK f377384
|
arminsabouri
left a comment
There was a problem hiding this comment.
To me this reads as the first 2 pages of a paper or the "learn more" portion of a website. There is a abstract, related works (spritual successor to jm), and breifly how. We might be one two different pages of what document we are trying to create and for whom?
There is two versions this README can take imo:
a project intro or a project overview.
This reads as the latter to me but **bc its the front page of the project ** it must be former. And honestly this might be a more accessible overview than what we have in #51.
An intro, however, is something that is no more than 3 paragraphs -- almost like an abstract. it must make certain assumptions about the reader and we can't explain every concept to them. i.e why privacy is important to Bitcoin or what clustering even is. We assume the reader is a dev or technical audience. Because that is who we are trying to reach in the very immediate future -- not end users. We will eventually reach them as well.
We have so many many other documents where we already explain these prelimenary concepts. Simialrly we cannot explain how we are going to do the things we say we are going to do. We just say we are going to do them and point them to where they can read more (this is specifically targeting the how part of this diff).
It has to comunicate:
- What the problem is with current solutions (while providing no background for these solutions. We just say coinjoins and payjoins have this problem)
- Why this matters (because privacy is overstated, etc... )
- How Fungi addresses the issues -- and explain this using common language and avoid jargon. The current how is using terms like intent. And going into too much detail for an intro.
| # Fungi | ||
|
|
||
| This repository contains documents that describe a family collaborative Bitcoin transaction construction protocols. The protocols form a progression towards decentralized and market based privacy preserving transactions. | ||
| Fungi is a protocol for collaborative transactions designed to make using Bitcoin more private. Participants can also pay each other interactively in these transactions, which helps not just privacy but also blockspace efficiency. |
There was a problem hiding this comment.
| Fungi is a protocol for collaborative transactions designed to make using Bitcoin more private. Participants can also pay each other interactively in these transactions, which helps not just privacy but also blockspace efficiency. | |
| Fungi is a protocol for collaborative transactions designed to make using Bitcoin more private and conserve block space. |
concision!!!
There was a problem hiding this comment.
funnily enough i had it that way before, but eventually relented after all the LLMs consistently beat me into submission saying that it doesn't say that interactive payments are done as part of these transactions
There was a problem hiding this comment.
fwiw this is still unchanged
|
I want to push back on some of this but I do think most of your feedback is still applicable...
I don't think it's mutuallye exclusive. I'm actually strongly leaning towards the latter, but I do think that it must have the former and must open with it. I erred on the side of tersneness and did not write a proper abstract, but just the most condensed 2 sentence description i could, ad then added that additional sentence about what interactive payments actually mean. I do think these are the primary features, but that this README does lack an abstract that is on the order of 2-3 paragraphs.
Yeah that's fair, but also that overview is meant as an overview not as an intro, it's a brief listing of the different aspects. Some of it like the synchronization mechanics I think can be removed into the spec, but the way i appraoched the overview is more to map everything out
disagree, the README is an entry point for anyone stumbling on the mdbook or the repo
but why would we want to only address that audience? i often see projects whose README is just a pile of factoids that have no better place, whereas this was conceived as (and is literally included in the mdbook) as the front matter addressing the broader audience the framing of the README as the front matter to the mdbook seems correct to me, people can read it till the end or just the first section,
actually only the problem definition doc discusses the clustering question as it's first section but in many paragraphs, and that document doesn't mention the censorship resistance or fungibility angle until the very end where both are taken for granted the overview doesn't discuss this at all, so unless you're referring to #72 there isn't anywhere where the "why does this need exist" question is really addressed
if you mean this about the README as a whole, i can't say i agree, IMO the problem with bitcoin privacy tech is that people keep portraying the lies-to-children versions of things as if they are the way things are "it's unlinkable because it uses blind signatures, trust me bro" the only way to say how fungi addresses this in such a short space is to just claim that it does it better without really qualifying how we can describe roughly what it does in that space but only in a way that doesn't actually differentiate it, but making a meaningful differentiation but if i take this feedback and apply it to the opening section of the README, then yes i agree it falls short |
I am not saying we only address that audience. We need to address a wide array of expertise. But in the next 3-4 weeks we will be addressing a technical / research focused audience. And getting their attention is crutial!
This README shouldnt have any of this stuff. an intro nor an abstract. Its just an unfortuante consequence bc this is the project homepage right now. A repo README should describe the repo and maybe a sentence or two about the project. Certainly not a background section. In the future all of this stuff should live elsewhere.
I agree that this space has / is been dishonest. But this is not the problem that we are solving. Fungi is solving a tehcnical problem. We're NOT solving privacy by just being honest. im not sure i understand your point here but I dont't think this ciritisim belongs in a the intro -- and I dont think its there now.
We always back up our claims if we produce mainnet software. just to be clear, I am not saying we dont do that. I just want to think about where and how to present those justifications. |
but why not? i don't really see a good justification for this assertion, the ones i can come up with aren't very compelling github displays it on the default page, in general i find READMEs are a very useful resource also this is the docs repo for the project, not the monorepo
i'm saying that IMO we need to adopt a higher standard of honesty in the communication than the current norms in the bitcoin privacy space... making claims that are only mostly true, or lack nuance because they sound good or please in group is a slippery slope that i'm very uncomfortable even flirting with
i really don't understand why it should be a short space... if it's about the start of the README then of course we should be efficient about it, but i think a project README should be more than just the bare minimum looking at joinmarket-{ng,clientserver}, bdk, ldk, ldk-node, ldk-server, they are comparable or more detailed |
arminsabouri
left a comment
There was a problem hiding this comment.
Couple things around the "how" section
| The [problem definition](docs/collaborative_txn_privacy.md) chapter discusses these on-chain privacy leaks in depth, and describes a particular transaction graph structure that resists deanonymization more robustly. | ||
|
|
||
| ### Semi-honest setting | ||
| ## How Fungi works |
There was a problem hiding this comment.
To me as a reader there is a disconnect at this point in the document. So far I have been told the fungi is : a protocol to make bitcoin more privacy, why privacy is important, and what the issues are with current solutions:
- txs measured in isolation
- Social graph / reoccuring relationships
- and the problems gets worse with every deanonymization
Somewhere in the problem def we also discuss a solution -> we must transact with unrelated peers and sybil resistance. Seperate point but this should live somewhere else.
Then the next sections starts by talking about payments in a queue. I would expect that there is at least a sentence or two explaining at a high level how fungi plans to solve these problems without having the reader understand granular details.
i.e I should be able to understand how fungi solves the "coinjoin privacy ignores post-mix activity" without having to understand why fungi needs intents in a queue:
e.g
Fungi evaluates transaction construction in the context of the wider transaction graph, building networks of transactions over time so that no small disclosure of information, such as how a coin is later spent can reliably de-anonymize a subset of users. To get there, peers construct transactions guided by a privacy preserving cost function and transact with randomly selected unrelated but incentive-compatible counterparts to resist clustering, and sybil attacks.
We should still have this depth first explination. But there needs to be a connecting sentence or something that lets the reader know why the thing they are reading is important or related
There was a problem hiding this comment.
A diagram for this could also help for those of us that are more visual learners.
There was a problem hiding this comment.
Having though thru this a bit more. I think this section should be still be labled as is. We can probably make it more concise. and my suggestiong for a highlevel / connecting paragraph can live above with the problem definition. This essentially becomes an abstract (and what i would give someone who wants to know about fungi in 3 paragraphs).
At the same time I would still have a intro sentence for the "how it works part". e.g in this section we will discuss the .... So the reader can decide do I need this information. (This parts more a nit)
There was a problem hiding this comment.
i guess the main intuition to get across here is that this is a familiar UX: users scan/click payment URIs (including for interactive payments), and then authorize their execution. but it's also quite different from the usual approach: the privacy optimization opportunities primarily come from telling the the wallet how long it can take to make these outcomes happen
would a short description of that is that more in line with your expectations?
as for a diagram - i am really not sure how to illustrate that, do you mind taking a stab? i do see it very visually in my mind, but i have no idea how to make that concrete without painstaking animations or something like that, i don't have a good idea for how to make a diagram (or do you mean something more like a flowchart as opposed to an architectural diagram?)
There was a problem hiding this comment.
would a short description of that is that more in line with your expectations?
My point is more about the sequence of ideas. Less about this subject matter of this particular section. (framing it the way you just did also would be useful -- besides the point)
To summarize the point above: its disconnecting for the reader to understand what the problems are and then for the next section to be about what a UX would look like. it needs some sort of connecting paragraph: something explaining how fungi solves these problems -- at a high level.
| # Fungi | ||
|
|
||
| This repository contains documents that describe a family collaborative Bitcoin transaction construction protocols. The protocols form a progression towards decentralized and market based privacy preserving transactions. | ||
| Fungi is a protocol for collaborative transactions designed to make using Bitcoin more private. Participants can also pay each other interactively in these transactions, which helps not just privacy but also blockspace efficiency. |
There was a problem hiding this comment.
fwiw this is still unchanged




No description provided.