decred / dcrdevdocs Goto Github PK

Reading decred/dcrd#2188 I'm getting the impression that there are two seeding methods in dcrd now, DNS and HTTPS. If that is correct, please add information about HTTPS seeding to the Peer Discovery page.

On https://devdocs.decred.org/developer-guides/blockchain-parameters/, the block reward share is still 60/30/10, which is outdated.

decred/dcrd#2315 introduced a bunch of new docs and resources to ease the use of simnet. We can link to this from https://devdocs.decred.org/environments/simnet/

Right now, we have a number of pages in Core Blockchain Concepts that are more technical references than "core concepts" (e.g. transaction format, addresses, utxo-set-semantics). Should we break these out into another top-level menu? Like Blockchain Reference or similar? Bitcoin dev docs do something similar with their Bitcoin Developer Reference which is separate from their Blockchain Guide (which we're kind of using as a template).

The following pages were part of the original outline for dcrdevdocs, but have not been written yet:

• /core-blockchain-concepts/chain-fork-sematics/
• /core-blockchain-concepts/proof-of-stake/proof-of-stake/
• /developer-guides/utxo-set-semantics/
• /contributing/core-values/
• /contributing/community/

These pages were removed in #43

Looking to do a wallets guide, similar to the Bitcoin dev docs wallet guide. Basic idea is to have a few high-level pages explaining basic concepts (perhaps filtering Bitcoin pages as a first pass), some pages that provide the technical documentation a wallet developer (or integrator) will need. My first inclination is to pull all of the (high quality) technical docs from the /dcrd and /dcrwallet repos into dcrdevdocs. It would be nice to have it all in one place, would look prettier and also make the v1.0 release more substantial. However, it might make more sense to keep some of that documentation "decentralized" in repos where it's easier for contributors to update. There could also be cases where a user will expect it there (e.g. installation instructions? repo-specific guidelines?). Therefore, I thought I'd just list the docs I think could be good for devdocs, see what people thought we should subtract/add. Also open to any ideas around wallet docs generally. Especially things we get asked in #support.

dcrwallet

• README
  • RPC API Specification
  • Client usage
  • Making API Changes

dcrd

• README
  • JSON-RPC Reference
  • Go Modules
  • Module Hierarchy

Assuming dcp-0005 passes (likely), we will need to update the documentation accordingly.

Items to update include:

• Block header format
• Merkle tree construction page
• Research pages related to proofs

Document differences in malleability fix, mining (nonce space), opcodes, etc.

When consensus change to add block commitments activates, also document it in context of comparing with efforts in Bitcoin (talks about stuffing that into OP_RETURN).

Alternatively to hosting it in dcrdocs, host it in the upcoming dev docs site.

Motivation: I guess that Decred hides many tech gems that are not often discussed, known or understood. Expose them, show how Decred engineering tradition prefers robust solutions over crutches and "temporary" workarounds. Expose it please. It will be useful for already insterested devs to learn how Decred works, and can also work as a magnet for new talent that values solid engineering.

I didn't read them but upon a quick look they seem to be detailed and high quality. How about link them somewhere in Developer Guides, or even ask mm if it's okay to import them in this repo?

https://stakey.club/en/querying-dcrdata/

https://stakey.club/en/dcrdata-running-your-own-block-explorer/

The following pages in the dcrdocs repo's Advanced section focus on technical details ostensibly only interesting for developers.

To move here:

• Block Header Specifications

Already moved here, possibly to be deleted from dcrdocs:

• Address Details
• Using Testnet
• Blockchain Parameters
• Transaction Details

The whole Research section should probably be moved here too.

The Contributing section has been already moved here and should probably be replaced by a link to these docs.

Referencing decred/dcrdocs#1066, @matheusd suggested the initial page was a good candidate for dev docs (it was originally meant for the user-facing docs but it was a bit too detailed). Let me know if anything needs to change.

I'm trying to teach myself Go.
In order to get a good idea about possible low-hanging-fruit that could be optimized in our software, I think it would be good to briefly document how to profile golang code.

I think it would fit nicely in the Contributing section of the docs.

I'm going to work on this, but I would welcome any tips from devs who are experienced at profiling in golang, and who have any suggestions.

https://devdocs.decred.org/developer-guides/addresses/#address-format

This gives give a good outline of the address format. Would be useful to provide links to code or code snippets which are example implementations.

Some more detail on the mainnet page would be nice. Quoting a comment from @s-ben

insert general advice about mainnet a dev would need. E.g. warnings about deploying to mainnet, what stage you need to be in to deploy to mainnet, any caveats/changes from simnet/testnet to think about

Need a page for how to do deterministic builds.

Recently I had to explain how the block approval/disapproval mechanic works and its consequences on Decred's blockchain.

It would be useful to have a dev doc page explaining it clearly and with more details and links to appropriate code.

Things I think are relevant to present:

• That voting on block approval is (only) a part of the whole PoS process
• That votes are for the previous block
• That a block that disapproves the parent undoes the utxo set changes made by the regular transaction tree
• How that is encoded in votes
• Consequences for applications
  • Needs to handle the case where txs are "reversed"

Copying from #14

https://github.com/jholdstock/dcrdevdocs/pull/14#discussion_r320546370

Settings -> Settings

I don't think we're very consistent with this (could be a separate Issue), but GUI elements we usually bold or style.

No idea how to do this. Putting this here so it can be added eventually.

The Minimum Voting Wallet is very useful with simnet, maybe a subsection to explain why and how use MVW.

https://github.com/raedahgroup/dcrdevdocs/blob/master/start.md

I noticed that on dcrdocs, we have some instructions on setting up a go environment. In @raedah's notes, we also have this Learning to code section, which recommends a go book (which was also recommended to me by lukebp when I started coding on Politeia). Wondering if we should put this content somewhere? The Contributor Guidelines page? A new page? Thoughts?

#3 added a bunch of new pages to dcrdevdocs. These need to be individually reviewed, polished and/or Decred-ified.

Done:

• core-blockchain-concepts/blockchain.md
• core-blockchain-concepts/hard-fork-voting-and-consensus-rule-changes.md
• core-blockchain-concepts/transactions/transactions.md
• core-blockchain-concepts/contracts.md
• core-blockchain-concepts/transaction-data.md (#25)
• protocol-p2p-network/blocks-first.md
• protocol-p2p-network/headers-first.md
• protocol-p2p-network/initial-block-download.md
• protocol-p2p-network/orphan-blocks.md
• protocol-p2p-network/transaction-broadcasting.md
• protocol-p2p-network/memory-pool.md (#26)
• protocol-p2p-network/peer-discovery.md (#12)
• environments/mainnet.md

In progress:

• core-blockchain-concepts/merkle-root-construction.md (#38)

Removed by #43:

• core-blockchain-concepts/compact-filters-for-spv.md
• core-blockchain-concepts/fork-detection.md
• core-blockchain-concepts/lottery-selection-semantics.md
• core-blockchain-concepts/proof-of-work.md
• transactions/opcodes.md
• protocol-p2p-network/block-broadcasting.md
• protocol-p2p-network/connecting-to-peers.md
• protocol-p2p-network/misbehaving-nodes.md

Back in November the developers were testing reproducible builds with Go 1.13. It would be nice to have instructions about verifying those builds compiled somewhere. I think devdocs is a better fit compared to docs, because building requires the toolchain installed.

High level overview of how dcrd/dcrwallet codebases diverged from btcd/btcwallet might be useful for new developers.

As a case in point, I've essentially rewritten txscript, secp256k1, ecdsa, schnorr, gcs, and huge swaths of blockchain just off the top of my head. Then there are others that Matheus did such as the addition of fees and basically a rewrite of bech32 to make it actually efficient.
84% new code seems very plausible.
Right, and btcd doesn't even have schnorr
Nor any of the connmgr updates like http seeding (davecgh on 2020-04-07)

what are:

stakesubmission
sstxcommitment
sstxchange
stakegen
the associate op returns

We decided in #21 to remove the contracts page.

Attached is the progress we made so far on the page:
contracts.txt

decred/dcrd#2181 captures Go error handling best practices accumulated from years of experience and discussions. This looks like valuable knowledge to start collecting in the dev docs. It would also be more safe in the devdocs repo, compared to GitHub issues (that are currently not archived by anyone afaik). As a small bonus, it would make for more "good tech read" pages available offline via Git.

The initial commits to this repo added some documentation files in bulk, mainly copied from bitcoin-centric sources. These have been removed from dcrdevdocs in #43 so we have a site which is suitable for production. These extra pages can be de-bitcoin-ified and added back to dcrdevdocs later. Here is a list of the pages.

• Developer Guides/Compact Filters for SPV
• Core Blockchain Concepts/Fork Detection
• Developer Guides/Lottery Selection Semantics Done in #88
• Transactions/Opcodes Done in #86
• Protocol P2P Network/Block Broadcasting
• Protocol P2P Network/Connecting to Peers
• Protocol P2P Network/Misbehaving Nodes
• Core Blockchain Concepts/Proof of Work

It looks like @davecgh has created a bunch of new content for the latest DCP,
https://github.com/davecgh/dcps/blob/dcp0005/dcp-0005/dcp-0005.mediawiki
https://github.com/decred/dcps/blob/master/dcp-0005/dcp-0005.mediawiki

Some of it presumably can't be used until the DCP passes (assuming it does). But it looks like there's some background content we could incorporate now? Perhaps the merkle root/trees, SPV, block filter sections?

There could also be some additional reusable content in the DCP archives?
https://docs.decred.org/governance/consensus-rule-voting/consensus-vote-archive/

I'm trying to teach myself Go.

Unit tests are highly valued for these projects. Unit tests are also a great way for new contributors to get familiar with a project, and can also serve as a form of documentation for how code works.

I think it would be a good idea to have a basic guide and "best practices" in the Contributing section of the dev docs, just to start collecting that knowledge there.

I'm thinking about having sections like:

• Example of how to run tests that are already there
• Example of how to run a specific test
• Best practices for writing good tests:
  • Table-driven tests
  • Subtests
• Measuring code coverage
• Finding areas of the codebase that need unit tests

I'm definitely not an expert on any of these topics, but I want to start aggregating information into a guide. I would welcome any tips or examples to follow from more experienced devs here!

All pages have been created from the same template, and as a result they all have the same icon in the header. We should update these to be relevant icons, or remove them if a relevant icon cannot be found

This comes out of #29

We dont have a contributor compensation page in dcrdevdocs because it is relevant to all contributors, not just devs. However we should probably link to the compensation page in dcrdocs somehow.

If Rosetta gains any traction, Decred's implementation may help to build software for Decred. It would be nice to represent it on the dev docs website.

Links:

• Rosetta launch announcement https://www.rosetta-api.org/blog/2020/06/17/2-introducing-rosetta.html
• Rosetta website https://www.rosetta-api.org/
• Intro https://www.rosetta-api.org/docs/welcome.html
• Decred announcement https://community.rosetta-api.org/t/decreds-rosetta-middleware-implementation/79
• Decred impl repo https://github.com/decred/dcrros

In the original outline, we have a Hard Fork Voting and Consensus Rule Changes page. Presumably inspired by this page in the Bitcoin dev docs,
https://bitcoin.org/en/blockchain-guide#consensus-rule-changes

I've rewritten the text, polishing it a bit (saved in the s-ben:hard-fork-consensus-page branch). But we realized this is probably different enough in Decred to warrant completely new text.

Explain the difference between, and purpose of scriptPubKey and scriptSig.

Some good reference for this:

• https://link.springer.com/chapter/10.1007/978-1-4842-5522-3_7
• https://www.mycryptopedia.com/bitcoin-script-explained/

Not including this in #86 because that PR is growing large already

#2 introduces the skeleton of a "Projects" page. This could use more fleshing out.

In order to easily search the code for notes/comments, we will use a standardised format for comments.

<!-- TODO <username>: <comment> -->

For example:

<!-- TODO jholdstock: We need to do some work here... -->

This issue can be closed once all comments have been removed.

Currently, dcrdocs and dcrdevdocs both use the same mkdocs template. This could cause confusion, because when a user clicks on a link to the other site (which will happen), they may not realize they are on another site. Therefore, we should visually differentiate dcrdevdocs from dcrdocs.