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
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
| ## Background | ||
|
|
||
| Censorship resistance and fungibility are among Bitcoin's foundational properties. Without privacy, both can be undermined largely outside the protocol's rules, whether by targeting specific individuals or through chilling effects. | ||
|
|
||
| Bitcoin transactions are public data, and they are connected in a graph structure. Chain analysis is the application of heuristics to this graph to infer which coins share an owner. While no heuristic is perfect, their effectiveness has been shown in numerous studies. Several heuristics can be combined for a more accurate analysis. Analysis might also draw on auxiliary information not recorded on the blockchain, such as which coins an exchange sent to which customer. | ||
|
|
||
| CoinJoin transactions seek to undermine some of the heuristics used to cluster coins across the transaction graph. They combine several users' inputs and outputs in one transaction in order to obscure ownership links within it. Several CoinJoin implementations exist with different approaches to their transaction structure. |
There was a problem hiding this comment.
I dont think we should justify why privacy is important for bitcoin in the README background section. WE have to assume somethings about the reader.
There was a problem hiding this comment.
the particular points in the 1st paragraph are just misconceptiosn that i do feel need to be addressed, which is the eric schmidt framing of value of privacy ("why would i need it i'm not ogling instagram models"), i find that this is a connection that people just don't make often enough
the 2nd and 3rd paragraph are just establishing terminology so not as needed, but i don't understand why they are problematic especially if it's clearly delineated that it's background info that people can skip?
i think the README should address a non-technical audience, i.e. casual bitcoin users should have just enough to decide whether or not they are going to try and dig further
|
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 |
No description provided.