Proposal: Merge "Operating Modes" And "P2P Network"

[David A. Harding]

Hi,

The Developer Guide currently has two adjacent sections (h2):

* Operating Modes (Full Node & SPV)
* P2P Network (Connection management & relaying)

I propose we merge them into a single Operating Modes section.

Rational: a program's operating mode largely determines how it interacts
with the network. For example, SPV clients don't relay. I believe
merging the sections will allow us to keep related information closer
together and better categorize normal behavior.

Other Considerations: combining the two sections will eliminate the
anchor link to P2P Networking, possibly semi-breaking a few incoming
links. (People wanting to go to the old P2P section will instead go to
the top of the page.) All other anchors should be unaffected.

If there's consensus for this change, I'll begin making it immediately.

Thanks,

-Dave
--
David A. Harding

[Saïvann Carignan]

That's an interesting suggestion! I'm certainly interested in hearing
other contributors' opinion on this.

TBH, I'm a little worried that this would kind of force us to drop some
content that is more specific to each subsection. What do you think?

(e.g. peer discovery, alerts aren't specific to operating modes)

The full protocol[1] also doesn't seem specific to operating modes,
should it eventually go into the P2P Network Specification page.

Another perhaps-not-so-important-design-issue is that this will create
an empty box on the devel-docs[2] page, due to having an odd number of
subsections :) Unless perhaps we also eventually merge "Mining" with
"Block Chain" since they are both short & related subsections.

All in all, I generally like to make things simple too!

[1] https://en.bitcoin.it/wiki/Protocol_specification
[2] https://bitcoin.org/en/developer-documentation

[David A. Harding]

On Mon, Jun 09, 2014 at 12:42:35AM -0400, Saīvann Carignan wrote:
> TBH, I'm a little worried that this would kind of force us to drop some
> content that is more specific to each subsection. What do you think?
>
> (e.g. peer discovery, alerts aren't specific to operating modes)

I wasn't planning on dropping any content, but you make a fair point
that some content isn't specific to a particular mode.

The problem I'm having is that different peers are using the network in
different ways. So do we describe network behavior in the operating
modes section, or do we describe how different operating modes use the
network in the networking section? I was hoping that merging would
eliminate the conundrum.

> The full protocol[1] also doesn't seem specific to operating modes,
> should it eventually go into the P2P Network Specification page.

That protocol page only addresses Bitcoin Core, so it's not
surprising that it looks modeless. For example, here's all it says
about Bloom filters:

filterload, filteradd, filterclear, merkleblock

These messages are related to Bloom filtering of connections and are defined in BIP 0037.

Neither the reference page nor the new examples page attempts to
duplicate the subsection hierarchy of the corresponding guide sections,
so I think we can order the reference information however we'd like.

> Another perhaps-not-so-important-design-issue is that this will create
> an empty box on the devel-docs[2] page, due to having an odd number of
> subsections :) Unless perhaps we also eventually merge "Mining" with
> "Block Chain" since they are both short & related subsections.

I'm not a fan of merging block chain and mining only because I think
mining is unimportant to the guide and should be near the bottom.

As for an empty box, I don' think that's a problem short-term and I'm
sure we can find a new section to put in its place. Maybe a Security &
Privacy section, or a glossary, or a Planned Improvements section, or
etc... (There's still lots to write!)

[David A. Harding]

Hey,

I was thinking about this some more as I was looking for a place to add
a subsection about the memory pool. Right now, the text in Operating
Modes[1] is all about payment validation, which is (it seems to me) a
wallet function.

[1] https://bitcoin.org/en/developer-guide#operating-modes

However, when I see "full node", I think "full peer"---as in a program
which relays txes, relays blocks, and answers queries for SPV clients.
That's all network-related stuff.

So, with that in mind, what do you all think about the following changes:

1. Merging Operating Modes (h2) into the Wallet Programs (h3) subsection
of Wallets (h2).

2. Moving Wallet Files (h3) into a new Keys (h2) section above
Wallets (h2).

3. Promoting Wallet Programs (h3) to h2 (and promoting all of its
children by a header level).

4. Moving Application Of Bloom Filters (h4) to the P2P Network
(h2) section as an h3. (Leaving the basic Bloom Filter text in the
Wallets section.)

To be clear, unlike my previous proposal, in this proposal we'd keep P2P
Networking. We'd also maintain an even number of sections, with a new
Keys section replacing the Operating Modes section.

I'd appreciate hearing your thoughts,

[Saïvann Carignan]

Hey,

@Greg @Chris I like when you bring some more opinions, if you have time ;) !

I still have mixed opinions on this, as I try to figure out all changes
correctly. But here's my first thoughts or suggestions;

Re: P2P Network / Operating modes: In case this makes any sense, I think
I like the idea of moving "Operating modes" under "P2P Network" (h2 ->
h3) instead, because operating modes is about being secure in a P2P
network, by using different interactions with peers and the block chain.
And this wouldn't (I think) block new content from being added.

Re: Wallets / Keys: The more I think of it, the more I like the idea..!
Still pondering :) . I perhaps find it a little confusing to associate
"HD Wallets" being under "Keys" instead of "Wallets". But maybe not..
All in all, having this as a separate section sounds good to me in
particular if there's more content planned regarding private keys /
addresses.

Re: Operating modes / Wallets: At a first glance, this one seems less
attractive to me, as I don't see this much relation between the two
(e.g. Most if not all types of wallet programs can work with different
operating modes).

Saīvann

[David A. Harding]

On Wed, Jun 11, 2014 at 11:04:42PM -0400, Saīvann Carignan wrote:
> here's my first thoughts or suggestions;

Thanks! I'm moved some of the quoted text below out of order.

> Re: Wallets / Keys: The more I think of it, the more I like the idea..!

Cool. I'll start making a todo list for that.

> I perhaps find it a little confusing to associate "HD Wallets" being
> under "Keys" instead of "Wallets".

I think HD wallets are misnamed, which is why I gave that section a
different name:

https://bitcoin.org/en/developer-guide#hierarchical-deterministic-key-creation

The only three occurences of "HD wallet" in the text all refer to wallet
programs using HD keys.

> All in all, having this as a separate section sounds good to me in
> particular if there's more content planned regarding private keys /
> addresses.

Yes. I think we're going to have to cover more of the elliptic curve
stuff. It was pretty easy to just hand key creation, signing, and
verification over to libssl in the beginning of Bitcoin, but now that's
moving into application space with HD keys, key rings/threshold
signatures, ECDH/stealth addresses, and whatever these crazy devs think
of next week. :-)

> Re: Operating modes / Wallets: this one seems less attractive to me,

> as I don't see this much relation between the two (e.g. Most if not
> all types of wallet programs can work with different operating modes).

Right now, Wallet Programs says: "This leaves us with three necessary,
but separable, parts of a wallet system: a public key distribution
program, a signing program, and a networked program."

We describe in detail various signing-only programs and (in less detail)
pubkey distribution programs, but we don't have a Networked Wallet
subsection.

I propose that Operating Modes become that Networked Wallets subsection.
It would then work with the other Wallet Program subsections to show how
full peer and SPV can combine with signing and key distribution
programs. For example, you can use a signing-only wallet with a full
peer (e.g. Armory) or an SPV client (e.g. Electrum offline, sort of).

> Re: P2P Network / Operating modes: In case this makes any sense, I

> like the idea of moving "Operating modes" under "P2P Network" because

> operating modes is about being secure in a P2P network

It does make sense. There's no doubt in my mind that operating modes is
strongly tied to P2P network. But I also think it's strongly tied to
networked wallets. And like the King Solomon parable, splitting it down
the middle doesn't work so well.

Thank you for the feedback. Greg, Chris, and others---I too would
appreciate hearing your thoughts.

Thanks,

[Saïvann Carignan]

Le 2014-06-12 04:13, David A. Harding a écrit :
>
>> Re: Operating modes / Wallets: this one seems less attractive to me,
>> as I don't see this much relation between the two (e.g. Most if not
>> all types of wallet programs can work with different operating modes).
>
> Right now, Wallet Programs says: "This leaves us with three necessary,
> but separable, parts of a wallet system: a public key distribution
> program, a signing program, and a networked program."
>
> We describe in detail various signing-only programs and (in less detail)
> pubkey distribution programs, but we don't have a Networked Wallet
> subsection.
>
> I propose that Operating Modes become that Networked Wallets subsection.
> It would then work with the other Wallet Program subsections to show how
> full peer and SPV can combine with signing and key distribution
> programs. For example, you can use a signing-only wallet with a full
> peer (e.g. Armory) or an SPV client (e.g. Electrum offline, sort of).

I'm starting to figure out your idea a little better! ( sorry, I'm not
always good at re-organizing stuff in my head, so please don't let me
hold interesting changes / pull reqs only for that :) ).

Don't you think this would leave "P2P Network" a little bit empty? Do we
have interesting stuff to put here over time?

Re: Mining, ah right, moving it to "block chain" was also intended to
give it less importance in the menus, but it is true that this would
actually move it at the top of the guide.. Probably a very good argument..

Saïvann

[Greg Sanders]

+1 on the idea. I'll definitely take the time to read it over once the changes are made to make sure it works well in practice.

re:p2p network, I think it's already long enough for what it is.