80f5feb1db
This is based on https://proposals.decred.org/proposals/c96290a but was modified in order to deal with realities that were unknown at the time of the specification draft. It is large and could not really be broken apart due to the pervasive use of the isTreasuryEnabled flag. It was primarily authored by * Marco Peereboom <marco@peereboom.us> * Dave Collins <davec@conformal.com> * Matheus Degiovani <opensource@matheusd.com> With additional contributions from * Donald Adu-Poku <donald.adu@gmail.com> * Jamie Holdstock <jholdstock@decred.org> Major changes: * Add decentralized treasury agenda, as specified in DCP0006, to all supported nets. * Add functions to determine if the decentralized treasury agenda is active at given block. * Add new opcode OP_TADD that is a nop in txscript but is used to tag scripts that credit the treasury account. This opcode is overloaded for treasurybase and for normal transactions. * Add new opcode OP_TSPEND that is a nop in txscript but is used to tag scripts that debit the treasury account. * Add new opcode OP_TGEN that is a nop in txscript but is used to tag P2PKH and P2SH outputs in a TSpend transaction. * Add functions that detect if a transaction is a valid TAdd, TSpend or treasurybase transaction. * Add error codes that return specific treasurybase/TAdd/TSpend consensus violations. * Modify countSpentOutputs to deal with treasury opcodes accordingly. * Modify indexBlock to skip treasury transactions that do not have inputs. * Add IsTreasuryEnabled call to ChainQueryer interface. * Add treasury logger for debugging and logging the decentralized treasury subsystem. * Add IsTreasuryActive flag to BlockConnectedNtfnsData and BlockDisconnectedNtfnsData. * Modify OP_SSGEN to allow an optional output that contains votes for a TSpend transaction hash. * Add function that returns TSpend votes from an SSGen transaction. * Modify CalcStakeVoteSubsidy so that treasurybase, unlike coinbase, is always awarded the full percentage of the assigned block reward. * Add helper functions to do all TSpend math so that callers don't roll their own. * Modify IsCoinBaseTx to not mistake a TSpend transaction as a coinbase. * Add checkTreasuryBase function that verifies that a treasurybase is properly constructed and pays the right amount to the treasury account. * Add functions to calculate treasury balance for the provided block hash/node. * Add function that verifies if a TSpend has a valid signature. * Add functions to determine if a TSpend is not overspending. * Add function to determine if a TSpend has been mined on the provided chain. * Add functions that count and verifies treasury spend votes. * Modify connectTransaction and disconnectTransactions to deal with the various treasury transactions. * Split CheckTransactionSanity in two functions checkTransactionSanityContextFree and checkTransactionSanityContextual. This is done in order to keep the decentralized treasury, which is always contextual, from infecting the context free checks. * Modify checkTransactionSanityContextual to recognize and verify treasury transactions. * Modify CheckTransactionSanity to deal with treasury transactions. * Split checkBlockSanity in two functions checkBlockSanityContextFree and checkBlockSanityContextual. This is done in order to keep the decentralized treasury, which is always contextual, from infecting the context free checks. * Modify checkBlockSanityContextual to enforce treasurybase and TAdd consensus checks. * Modify checkBlockPositional by unindenting it and adding TSpend consensus enforcement. * Modify checkCoinbaseUniqueHeightWithAddress to deal with the removal of the project subsidy from output 0. * Add checkCoinbaseUniqueHeightWithTreasuryBase that verifies coinbase and treasurybase in the provided block. * Unindent checkBlockContext. * Modify checkTicketRedeemerCommitments and checkVoteInputs to deal with potential tspend votes. * Modify CheckTransactionInputs to skip treasurybase transactions. * Modify CheckTransactionInputs to deal with TSpend transactions. Ensure the provided Pi key is valid and that the signature is valid for the transaction. Ensure that treasury TAdd and TSpend transaction utxo can only be spent after coinbase maturity. * Modify CountSigOps to deal with treasury transactions. * Modify CountP2SHSigOps to deal with treasury transactions. * Modify getStakeTreeFees to skip treasury transactions. Modify totalOutputs to subtract ValueIn 0 for TSpend and treasurybase transactions. * Modify checkTransactionsAndConnect to deal with modified amounts. * Add tspendChecks function that verifies an entire TSpend transaction validity at the point of the provided block. It ensures a TSpend is on a TVI. It ensures the TSpend is in the valid window. It verifies that a TSpend In and Out amounts match. It ensures a TSpend has the ValueIn amount encoded in the OP_RETURN in Out 0. It ensures a TSpend has not been mined before on this chain. It ensures a TSpend has the requisite votes. It ensures a TSpend is not overspending. * Modify checkConnectBlock to call checkTreasuryBase and tspendChecks when treasury agenda is active. * Add two tables to the database. Table "treasury" records the balance as of this block and balance changes that occurred in this block which will become active in CoinbaseMaturity blocks. Table "tspend" records all block hashes where a TSpend has been mined this is to detect forks and prevent a Tspend from being mined more than once. * Modify handleBlockchainNotification to communicate if the treasury agenda is active and skip treasurybase transaction when needed. * Add various Treasury parameters to chaincfg params. * Add hardcoded Tspend signatures in dcr_tmux_simnet_setup.sh. * Add notifytspend and stoptspend calls to the RPC server. notifytspend notifies the mempool when a TSpend transaction arrives. * Modify commit filters V2 to recognize TAdd and TSpend transactions. It was possible to modify V2 instead of introducing V3 because nothing changes from the viewpoint of the wallet and treasury opcodes are disallowed prior to agenda activation. * Modify AddMemPoolTransaction to skip TSpend transactions that would throw the fee estimator off. * Add IsTreasuryAgendaActive, OnTSpendReceived and TSpendMinedOnAncestor to mempool.Config in order to reject/accept TSpends in the mempool. * Modify checkPoolDoubleSpend to ignore treasurybase. * Modify mempool.maybeAcceptTransaction to enforce treasury standardness rules. Don't allow TSpend transactions prior to stake validation height. Skip treasurybase and tspend transactions in the orphan test. Ensure a tspend is in a valid window. Ensure not more than 7 TSpends are active in the mempool. Ensure TSpend has a well-known Pi key. Ensure The provided Pi key was used to sign the transaction. Ensure TSpend was not mined in an ancestor block. Notify subscribers that a valid TSpend was received. * Add standardCoinbaseOpReturn and standardTreasurybaseOpReturn to create an OP_RETURN followed by a data push that little endian encodes the height of the block. Then there are a number of random bytes to ensure that the transaction hash is always random. * Modify createCoinbaseTx to create a coinbase that is valid when treasury is enabled or not. Additionally, alter the transaction version if treasury is enabled. * Add createTreasuryBaseTx that creates a standard treasurybase. * Modify maybeInsertStakeTx to recognize treasurybase and TSpend transactions. * Modify handleTooFewVoters to call createTreasuryBaseTx when the treasury agenda is active. Skip copying treasurybase. * Modify NewBlockTemplate to recognize and deal with treasury transactions. Skip TSpend transaction if block is not a TVI. Skip TSpend transaction if it is not in the proper window. Skip TSpend transaction if a TSpend does not have enough yes votes. Skip TSpend transaction if it overspends the treasury account. Skip TAdd if there are more than 20 TAdds in the block. Create treasurybase if required. Insert valid TAdd/TSpend transactions into stake tree. * Add TreasuryBalance and IsTreasuryAgendaActive to rpcserver Chain interface. * Add gettreasurybalance, sendfromtreasury and sendtotreasury calls to RPC server. * Add notifytspend and stopnotifytspend to RPC websocket commands. * Add simnet miner to generate large number of blocks during rpctests without triggering PoW difficulty increases. This is used to verify various treasury and tspend conditions during CI/CT. * Modify RPC voting wallet to also vote on TSpends. * Add json tests to verify all new opcodes and corner cases in the script engine. * Modify isStakeOpcode to recognize treasury opcodes. * Modify countSigOpsV0 to count TSpends. * Modify handleStakeOutSign to deal with TSpends. * Modify SignTxOutput to recognize TSpends. * Add TSpendSignatureScript that signs a TSpend transaction. * Add TreasuryAddTy and TreasurySpendTy types to the standard scripts. * Add isTreasuryAddScript and isTreasurySpendScript functions that recognize a form of TAdd and TSpend transactions. * Modify ExtractPkScriptAddrs to deal with TAdd and TSpend outputs. * Add TxVersionSeqLock = 2 and TxVersionTreasury = 3 to wire. This is used to discriminate between treasury and non-treasury scripts. * Rig up all functions that need the isTreasuryEnabledflag directly or indirectly. * Shuffle various functions around and export them when they were needed to be called from other packages. * Added and modified numerous tests to verify (hopefully) all corner cases that the decentralized treasury agenda has added. |
||
|---|---|---|
| .. | ||
| assets | ||
| release-notes | ||
| code_contribution_guidelines.md | ||
| configure_peer_server_listen_interfaces.md | ||
| configure_rpc_server_listen_interfaces.md | ||
| configuring_tor.md | ||
| default_ports.md | ||
| json_rpc_api.mediawiki | ||
| README.md | ||
| simnet_environment.mediawiki | ||
Table of Contents
1. About
dcrd is a full node Decred implementation written in Go, and is licensed under the copyfree ISC License.
This software is currently under active development. It is extremely stable and has been in production use since February 2016.
It also properly relays newly mined blocks, maintains a transaction pool, and relays individual transactions that have not yet made it into a block. It ensures all individual transactions admitted to the pool follow the rules required into the block chain and also includes the vast majority of the more strict checks which filter transactions based on miner requirements ("standard" transactions).
2. Getting Started
2.1 Installation
The first step is to install dcrd. The installation instructions can be found here.
2.2 Configuration
dcrd has a number of configuration
options, which can be viewed by running: $ dcrd --help.
2.3 Controlling and Querying dcrd via dcrctl
dcrctl is a command line utility that can be used to both control and query dcrd via RPC. dcrd does not enable its RPC server by default; You must configure at minimum both an RPC username and password or both an RPC limited username and password:
- dcrd.conf configuration file
[Application Options]
rpcuser=myuser
rpcpass=SomeDecentp4ssw0rd
rpclimituser=mylimituser
rpclimitpass=Limitedp4ssw0rd
- dcrctl.conf configuration file
[Application Options]
rpcuser=myuser
rpcpass=SomeDecentp4ssw0rd
OR
[Application Options]
rpclimituser=mylimituser
rpclimitpass=Limitedp4ssw0rd
For a list of available options, run: $ dcrctl --help
2.4 Mining
dcrd supports the getwork
RPC. The limited user cannot access this RPC.
1. Add the payment addresses with the miningaddr option.
[Application Options]
rpcuser=myuser
rpcpass=SomeDecentp4ssw0rd
miningaddr=DsExampleAddress1
miningaddr=DsExampleAddress2
2. Add dcrd's RPC TLS certificate to system Certificate Authority list.
cgminer uses curl to fetch data from the RPC server.
Since curl validates the certificate by default, we must install the dcrd RPC
certificate into the default system Certificate Authority list.
Ubuntu
- Copy rpc.cert to /usr/share/ca-certificates:
# cp /home/user/.dcrd/rpc.cert /usr/share/ca-certificates/dcrd.crt - Add dcrd.crt to /etc/ca-certificates.conf:
# echo dcrd.crt >> /etc/ca-certificates.conf - Update the CA certificate list:
# update-ca-certificates
3. Set your mining software url to use https.
$ cgminer -o https://127.0.0.1:9109 -u rpcuser -p rpcpassword
3. Help
3.1 Network Configuration
- What Ports Are Used by Default?
- How To Listen on Specific Interfaces
- How To Configure RPC Server to Listen on Specific Interfaces
- Configuring dcrd with Tor
3.2 Wallet
dcrd was intentionally developed without an integrated wallet for security reasons. Please see dcrwallet for more information.
4. Contact
4.1 Community
If you have any further questions you can find us at:
https://decred.org/community/
5. Developer Resources
5.1 Code Contribution Guidelines
5.2 JSON-RPC Reference
5.3 Go Modules
The following versioned modules are provided by dcrd repository:
- rpcclient/v4 - Implements a robust and easy to use Websocket-enabled Decred JSON-RPC client
- dcrjson/v3 - Provides infrastructure for working with Decred JSON-RPC APIs
- rpc/jsonrpc/types - Provides concrete types via dcrjson for the chain server JSON-RPC commands, return values, and notifications
- wire - Implements the Decred wire protocol
- peer/v2 - Provides a common base for creating and managing Decred network peers
- blockchain/v2 -
Implements Decred block handling and chain selection rules
- stake/v2 - Provides an API for working with stake transactions and other portions related to the Proof-of-Stake (PoS) system
- standalone - Provides standalone functions useful for working with the Decred blockchain consensus rules
- txscript/v2 - Implements the Decred transaction scripting language
- dcrec - Provides constants
for the supported cryptographic signatures supported by Decred scripts
- secp256k1/v2 - Implements the secp256k1 elliptic curve
- edwards/v2 - Implements the edwards25519 twisted Edwards curve
- database/v2 - Provides a database interface for the Decred block chain
- dcrutil/v2 - Provides Decred-specific convenience functions and types
- chaincfg/v2 - Defines
chain configuration parameters for the standard Decred networks and allows
callers to define their own custom Decred networks for testing puproses
- chainhash - Provides a generic hash type and associated functions that allows the specific hash algorithm to be abstracted
- certgen - Provides a function for creating a new TLS certificate key pair, typically used for encrypting RPC and websocket communications
- addrmgr - Provides a concurrency safe Decred network address manager
- connmgr/v2 - Implements a generic Decred network connection manager
- hdkeychain/v2 - Provides an API for working with Decred hierarchical deterministic extended keys
- gcs - Provides an API for building and using Golomb-coded set filters useful for light clients such as SPV wallets
- lru - Implements a generic concurrent safe least-recently-used cache with near O(1) perf
5.4 Module Hierarchy
The following diagram shows an overview of the hierarchy for the modules provided by the dcrd repository.
6. Simulation Network (--simnet)
When developing Decred applications or testing potential changes, it is often extremely useful to have a test network where transactions are actually mined into blocks, difficulty levels are low enough to generate blocks on demand, it is possible to easily cause chain reorganizations for testing purposes, and otherwise have full control over the network.
In order to facilitate these scenarios, dcrd provides a simulation network
(--simnet), where the difficulty starts extremely low to enable fast CPU
mining of blocks. Simnet also has some modified functionality that helps
developers avoid common issues early in development.
See the full reference for more details: