github.com/dawnbass68/maddcash@v0.0.0-20201001105353-c91c12cb36e5/CONTRIBUTING.md (about) 1 # Blockbook Contributor Guide 2 3 Blockbook is back-end service for Trezor wallet. Although it is open source, the design and development of the core packages 4 is done by Trezor developers in order to keep Blockbook compatible with Trezor. 5 6 Bug fixes and support for new coins are welcome. Please take note that non-fixing pull requests that change base 7 packages or another coin code will not be accepted. If you have a need to change some of the existing code, please file 8 an issue and discuss your request with Blockbook maintainers. 9 10 ## Development environment 11 12 Instructions to set up your development environment and build Blockbook are described in a separate 13 [document](/docs/build.md). 14 15 ## How can I contribute? 16 17 ### Reporting bugs 18 19 A great way to contribute to the project is to send a detailed report when you encounter an issue. We always appreciate 20 a well-written, thorough bug report, and will thank you for it! 21 22 Check that [our issue database](https://github.com/trezor/blockbook/issues) doesn't already include that problem or 23 suggestion before submitting an issue. If you find a match, you can use the "subscribe" button to get notified on 24 updates. Do not leave random "+1" or "I have this too" comments, as they only clutter the discussion, and don't help 25 resolving it. However, if you have ways to reproduce the issue or have additional information that may help resolving 26 the issue, please leave a comment. 27 28 Include information about the Blockbook instance, which is shown at the Blockbook status page or returned by API call. For example execute `curl -k https://<server name>:<public port>/api` to get JSON containing details about Blockbook and Backend installation. Ports are listed in the [port registry](/docs/ports.md). 29 30 Also include the steps required to reproduce the problem if possible and applicable. This information will help us 31 review and fix your issue faster. When sending lengthy log-files, consider posting them as a gist 32 (https://gist.github.com). 33 34 ### Adding coin support 35 36 > **Important notice**: Although we are happy for support of new coins, we do not have enough capacity to run them all 37 > on our infrastructure. We run Blockbook instances only for selected number of coins. If you want to have Blockbook 38 > instance for your coin, you will have to deploy it to your own server. 39 40 Trezor harware wallet supports over 500 coins, see https://trezor.io/coins/. You are free to add support for any of 41 them to Blockbook. Currently implemented coins are listed [here](/docs/ports.md). 42 43 You should follow the steps below to get smooth merge of your PR. 44 45 #### Add coin definition 46 47 Coin definitions are stored in JSON files in *configs/coins* directory. They are the single source of Blockbook 48 configuration, Blockbook and back-end package definition and build metadata. Since Blockbook supports only single 49 coin index per running instance, every coin (including testnet) must have single definition file. 50 51 All options of coin definition are described in [config.md](/docs/config.md). 52 53 Because most of coins are fork of Bitcoin and they have similar way to install and configure their daemon, we use 54 templates to generate package definition and configuration files during build process. Similarly, there are templates for Blockbook 55 package. Templates are filled with data from coin definition. Although normally all package definitions are generated automatically 56 during the build process, sometimes there is a reason to check what was generated. You can create them by calling 57 `go run build/templates/generate.go coin`, where *coin* is name of definition file without .json extension. Files are 58 generated to *build/pkg-defs* directory. 59 60 Good examples of coin configuration are 61 [*configs/coins/bitcoin.json*](configs/coins/bitcoin.json) and 62 [*configs/coins/ethereum.json*](configs/coins/ethereum.json) for Bitcoin type coins and Ethereum type coins, respectively. 63 64 Usually you have to update only a few options that differ from the Bitcoin definition. At first there is base information 65 about coin in section *coin* – name, alias etc. Then update port information in *port* section. We keep port series as 66 listed in [the port registry](/docs/ports.md). Select next port numbers in the series. Port numbers must be unique across all 67 port definitions. 68 69 In the section *backend* update information how to build and configure back-end service. When back-end package is built, 70 build process downloads installation archive, verifies and extracts it. How it is done is described in 71 [build guide](/docs/build.md#on-back-end-building). Naming conventions and versioning are described 72 also in [build guide](/docs/build.md#on-naming-conventions-and-versioning). You have to update *package_name*, 73 *package_revision*, *system_user*, *version*, *binary_url*, *verification_type*, *verification_source*, 74 *extract_command* and *exclude_files*. Also update information whether service runs mainnet or testnet network in 75 *mainnet* option. 76 77 In the section *blockbook* update information how to build and configure Blockbook service. Usually they are only 78 *package_name*, *system_user* and *explorer_url* options. Naming conventions are are described 79 [here](/docs/build.md#on-naming-conventions-and-versioning). 80 81 Update *package_maintainer* and *package_maintainer_email* options in the section *meta*. 82 83 Execute script *go run contrib/scripts/check-and-generate-port-registry.go -w* that checks mandatory ports and 84 uniqueness of ports and updates registry of ports *docs/ports.md*. 85 86 Now you can try to generate package definitions as described above in order to check outputs. 87 88 #### Add coin implementation 89 90 Coin implementation is stored in *bchain/coins* directory. Each coin must implement interfaces *BlockChain* and 91 *BlockChainParser* (both defined in [bchain/types.go][/bchain/types.go]) and has registered factory function by 92 *init()* function of package *blockbook/bchain/coins* ([bchain/coins/blockchain.go](/bchain/coins/blockchain.go)). 93 94 There are several approaches how to implement coin support in Blockbook, please see examples below. 95 96 Bitcoin package *blockbook/bchain/coins/btc* is a reference implementation for Bitcoin-like coins. Most of the functionality 97 is usually the same so particular coin should embed it and override just different parts. 98 99 Bitcoin uses binary WIRE protocol thus decoding is very fast but require complex parser. Parser translate whole 100 pubkey-script to database ID and therefore it is usually possible store transactions without change. 101 102 ZCash package *blockbook/bchain/coins/zec* on the other side uses JSON version of RPCs therefore it doesn't require 103 specialized parser. Only responsibility that parser has is to translate address to Address Descriptor (used as 104 address ID in the database) and vice versa. 105 106 Ethereum package *blockbook/bchain/coins/eth* has own stand alone implementation because Ethereum uses totally 107 different concept than Bitcoin. 108 109 ##### BlockChain interface 110 111 Type that implements *bchain.BlockChain* interface ensures communication with the block chain network. Because 112 it calls node RPCs, it usually has suffix RPC. 113 114 Initialization of object is separated into two stages. At first there is called factory method (details described 115 in the next section) and then *bchain.BlockChain.Initialize()* method. Separated initialization method allows you call 116 inherited methods during initialization. However it is common practice override fields of embedded structure in factory 117 method. 118 119 Initialization routine usually loads chain information, registers message queue callback and creates mempool 120 and parser objects. 121 122 BitcoinRPC uses *btc.RPCMarshaller* ([btc/codec.go](/bchain/coins/btc/codec.go)) in order to distinguish API version of 123 Bitcoin RPC. Current API (*btc.JSONMarshalerV2*) uses JSON object with method arguments. Older API (*btc.JSONMarshalerV1*) 124 uses JSON array with method arguments and some arguments are defined differently (e.g. bool vs int). 125 126 For example see [zec/zcashrpc.go](/bchain/coins/zec/zcashrpc.go). 127 128 ##### BlockChain factory function 129 130 Factory function must be *coins.blockChainFactory* type ([coins/blockchain.go](/bchain/coins/blockchain.go)). It gets 131 configuration as JSON object and handler function for PUSH notifications. All factory functions have registered by 132 *init()* function of package *blockbook/bchain/coins* ([coins/blockchain.go](/bchain/coins/blockchain.go)). Coin name 133 must correspond to *coin.name* in coin definition file (see above). 134 135 Configuration passed to factory method is coin specific. For types that embed *btc.BitcoinRPC,* configuration must 136 contain at least fields referred in *btc.Configuration* ([btc/bitcoinrpc.go](/bchain/coins/btc/bitcoinrpc.go)). 137 138 For types that embed base struct it is common practice to call factory method of the embedded type in order to 139 create & initialize it. It is much more robust than simple struct composition. 140 141 For example see [zec/zcashrpc.go](/bchain/coins/zec/zcashrpc.go). 142 143 ##### BlockChainParser interface 144 145 Type that implements *bchain.BlockChainParser* interface ensures parsing and conversions of block chain data. It is 146 initialized by *bchain.BlockChain* during initialization. 147 148 There are several groups of methods defined in *bchain.BlockChainParser*: 149 150 * *GetAddrDescFromVout* and *GetAddrDescFromAddress* – Convert transaction addresses to *Address Descriptor* that is used as database ID. 151 Most of coins use output script as *Address Descriptor*. 152 * *GetAddressesFromAddrDesc* and *GetScriptFromAddrDesc* – Convert *Address Descriptor* to addresses and output script. Note that 153 *btc.BitcoinParser* uses pointer to function *OutputScriptToAddressesFunc* that is called from *GetAddressesFromAddrDesc* 154 method in order to rewrite implementation by types embedding it. 155 * *PackTxid* and *UnpackTxid* – Packs txid to store in database and vice versa. 156 * *ParseTx* and *ParseTxFromJson* – Parse transaction from binary data or JSON and return *bchain.Tx*. 157 * *PackTx* and *UnpackTx* – Pack transaction to binary data to store in database and vice versa. 158 * *ParseBlock* – Parse block from binary data and return *bchain.Block*. 159 160 Base type of parsers is *bchain.BaseParser*. It implements method *ParseTxFromJson* that should be the same for all 161 Bitcoin-like coins. Also implements *PackTx* and *UnpackTx* that pack and unpack transactions using protobuf. Note 162 that Bitcoin stores transactions in more compact binary format. 163 164 *bchain.BaseParser* stores pointer to function *bchain.AddressFactoryFunc* that is responsible for making human readable 165 address representation. See [*bch.bcashparser*](/bchain/coins/bch/bcashparser.go) for example of implementation that uses 166 different approach for address representation than Bitcoin. 167 168 #### Add tests 169 170 Add unit tests and integration tests. **Pull requests without passing tests will not be accepted**. 171 How to implement tests is described [here](/docs/testing.md). 172 173 #### Deploy public server 174 175 Deploy Blockbook server on public IP address. Blockbook maintainers will check your implementation before merging.